webtranslateit-payday 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c69e90db47eb429202583e59002641017e200efa98a05989a8112db2504ca8d6
-  data.tar.gz: 0e1a0a649e12c88225f5eafd95bc7b2eb2f1a1b3825570ca54611ea072d16a6a
+  metadata.gz: 4cb98acc78809a09e4945f8d8525aee1bbafd3ed17a45234be6fb0a8836f3135
+  data.tar.gz: b3379b263fb55f5d7fdb8ec48d66924e0f0b1110325b43e15bbd0a764fbc6154
 SHA512:
-  metadata.gz: 3bfaddfd9cbd922672a519e1309e723a8abfa5e64d035e1d3e355c9437ce93d0734fdfbfb7b624b1389f2ff66dc65685327a9cd802826055468b6353351df606
-  data.tar.gz: beac41f39e7cc6013e6eb7f94057e55042daad14c73a17b33a2e99bbcbc8b23d0b63e4c67618c5338298131e02c3f1614349d89983a42805ac693d76a0df1625
+  metadata.gz: c0473911f660484293361d1fbfb7020efed4614c06dd89b000fc7995f90e52b995c763781f175609578fd42090923ed9969baab0d4bffb85140f887356964690
+  data.tar.gz: 0a401edbb42eb073bf35602caaf6c2b7b762450dff19a04f2a8ee4d3ae8aca0ecf2ceab4485300a0647a2005b22116edd2cd1eba0be60a07117f5d44e5637b39

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.

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/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/pdf_renderer.rb

@@ -13,13 +13,14 @@ 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
@@ -39,8 +40,9 @@ module Payday
     end
     private_class_method :currency_for
 
-    def initialize(invoice)
+    def initialize(invoice, appendix: nil)
       @invoice = invoice
+      @appendix = Appendix.wrap(appendix)
       @dependencies = {}
     end
 
@@ -49,13 +51,44 @@ 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

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.0'
   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.0
 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