tallyman 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ccb3bfdda5d49f50b0902f0bb78996c507d66f5f6847322b4dd68be31615d9f
+  data.tar.gz: 4202cc126a5556d17239a9989d7ab11a7dd6c8de19de42e885494a0669776c76
+SHA512:
+  metadata.gz: 932d8e285879146e5dcc42b17939ad2f324cbf7fea0eb744681a1572c43ee868cc9a453f1b2be4bfac594ebd5e7d13939af505630f3c4dbd84984232d6005b16
+  data.tar.gz: 4df8d76b15d53096521ca7d8835870ad89225b1c15d9d80073bbeab3f6e7db476ba227e225381a8a9495ebd52b46aa88723b9da8e64fdec37fb9b7f9777f91b5

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# CHANGELOG
+
+## 1.0.0 (2026-11-11)
+
+The first release of Tallyman. It carries on from [Payday](https://github.com/webtranslateit/payday), which was published as `webtranslateit-payday`, and picks up where that gem's 2.1.2 left off. Everything before this release is in [Payday's changelog](https://github.com/webtranslateit/payday/blob/main/CHANGELOG.md).
+
+Invoice amounts and layout are exactly what they were in `webtranslateit-payday` 2.1.2; only the translated labels listed below differ. To move an application over:
+
+* In your Gemfile, replace `gem 'webtranslateit-payday', require: 'payday'` with `gem 'tallyman'`.
+* Rename the `Payday` module to `Tallyman` wherever you use it: `Tallyman::Invoice`, `Tallyman::Config`, `Tallyman::Invoiceable`, `Tallyman::LineItemable`, `Tallyman::Appendix` and so on.
+* If you override the invoice labels, move your translations from the `payday:` I18n key to `tallyman:`.
+
+A few things change along the way:
+
+* The Rails generator, now `rails generate tallyman:setup`, works on current Rails. It used to fail on Rails 7.1 and later, and the migration it wrote could not run. The migration now creates every column an invoice needs to render, and models generated under custom names (`--invoice-name`, `--line-item-name`) are wired so that the invoice finds its lines.
+* An ActiveRecord invoice with a `bill_to` column is billed to whoever that column names. `Invoiceable#bill_to` used to shadow the column with its placeholder, so such an invoice was addressed to "Goofy McGoofison" unless the model redefined the method.
+* The translations are reviewed, so invoices in French, Spanish, German, Dutch and Simplified Chinese print some labels differently. English is untouched.
+  * Every locale now translates every label. Dutch, German and Simplified Chinese were missing the receipt number, and Dutch and Simplified Chinese the REFUNDED stamp, so those came out in English.
+  * The amount column no longer reads as a second price in French ("Montant"), Spanish ("Importe") or as "total" in Simplified Chinese ("金额").
+  * Spanish: the paid date is "Fecha de pago:", the stamps are "VENCIDO" and "REEMBOLSADO", the unit price is "Precio unitario", and the retention line is "Retención:" without "IRPF", which only applies in Spain.
+  * German: the shipping address is "Lieferadresse", the retention line "Einbehalt:" and the refunded stamp "ERSTATTET".
+  * Dutch: "Faktuur" is spelled "Factuur", and the addresses, due date, shipping line, overdue stamp and quantity use the usual invoice wording.
+  * Simplified Chinese: the invoice number, due date, shipping line and the paid and overdue stamps use the usual invoice wording.
+
+  To keep a label as it was, override it under your locale's `tallyman` key. To name IRPF on a Spanish retention line, set `retention_description` on the invoice.

data/README.md

@@ -0,0 +1,219 @@
+# Tallyman
+
+Tallyman is a Ruby library for rendering invoices to PDF.
+
+Here's an [example invoice](https://github.com/Rebase-Capital/tallyman/raw/main/spec/assets/testing_predefined_amount.pdf).
+
+## What is a tallyman?
+
+On the docks, the tallyman is the clerk who stands at the ship's side and counts the cargo as it comes over the rail. Every bale, crate and barrel is checked off against the manifest, and the tally that results is the record both the ship and the shipper are held to: what was delivered, in what quantity, and so what is owed.
+
+This gem does the same job on paper. You hand it what was sold and to whom, and it draws up the bill.
+
+## Installing
+
+```
+gem install tallyman
+```
+
+Or, using Bundler:
+
+``` ruby
+gem 'tallyman'
+```
+
+Tallyman needs Ruby 3.2 or later.
+
+## Usage
+
+Tallyman comes with `Invoice` and `LineItem` classes you can use as they are:
+
+``` ruby
+invoice = Tallyman::Invoice.new(invoice_number: 12)
+# Two lines with a price and a quantity. The amount is price * quantity.
+invoice.add_line_item(price: 20, quantity: 5, description: 'Pants')
+invoice.add_line_item(price: 10, quantity: 3, description: 'Shirts')
+# A line with no price or quantity, only a predefined amount (a flat fee).
+invoice.add_line_item(predefined_amount: 10, description: 'Shipping')
+invoice.render_pdf_to_file('/path/to_file.pdf')
+```
+
+`render_pdf` returns the PDF as a string instead of writing it to disk.
+
+API documentation is available at [rubydoc.info](https://www.rubydoc.info/gems/tallyman).
+
+## Customizing your invoice
+
+`Tallyman::Config` holds the settings shared by every invoice, such as the logo and the company details:
+
+``` ruby
+Tallyman::Config.default.invoice_logo = "/path/to/company/logo.png"
+Tallyman::Config.default.company_name = "Awesome Corp"
+Tallyman::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
+Tallyman::Config.default.invoice_logo = {filename: "logo.svg", size: "200x50"}
+```
+
+`page_size` accepts `"LETTER"`, `"A4"` and `"LEGAL"`. `currency` and `date_format` are set the same way.
+
+## QR codes
+
+An invoice can carry a QR code, which a growing number of countries expect for tax compliance:
+
+``` ruby
+invoice = Tallyman::Invoice.new(
+  invoice_number: 12345,
+  qr_code: 'https://verify.example.com/invoice/12345',
+  notes: 'Scan the QR code below to verify this invoice online.'
+)
+```
+
+The QR code is rendered below the notes, as vector SVG so it stays 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 Tallyman with ActiveRecord (or any other objects)
+
+Tallyman works with two objects, an invoice and a line item. To use it with your own classes, include `Tallyman::Invoiceable` in the invoice and `Tallyman::LineItemable` in the line item.
+
+In a Rails app, a generator writes both models and the migration for their tables:
+
+```
+rails generate tallyman:setup
+```
+
+Run it with `--help` to see how to name the models differently or skip the migration.
+
+If you write the classes yourself, an invoice needs to respond to `line_items`, `bill_to`, `invoice_number`, `notes`, `due_at`, `paid_at`, `tax_rate`, `tax_description`, `shipping_rate`, `shipping_description`, `retention_rate` and `retention_description`. The three rates must be numbers, 0 when they don't apply; the rest can be `nil`. A line item needs `description`, `price`, `quantity`, `predefined_amount`, `display_price` and `display_quantity`.
+
+## Rendering PDFs to the web
+
+In a Rails controller, send the rendered string straight to the browser:
+
+``` ruby
+respond_to do |format|
+  format.html
+  format.pdf do
+    send_data invoice.render_pdf, filename: 'Invoice #12.pdf', type: 'application/pdf', disposition: 'inline'
+  end
+end
+```
+
+## Appending your own pages
+
+Pass a `Tallyman::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 = Tallyman::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 Tallyman'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 lists it on a page of its own:
+
+``` typst
+#let shipments = json(bytes(sys.inputs.shipments))
+
+#pagebreak()
+#text(size: 16pt, weight: "bold")[Shipments]
+
+#for shipment in shipments [
+  - #shipment.reference
+]
+```
+
+## I18n
+
+Tallyman uses the i18n gem for its labels, and ships with English, French, German, Spanish, Dutch and Simplified Chinese. To change a label, add a YAML file to the `config/locales` directory of your Rails app. These are the labels you can override:
+
+``` yaml
+en:
+  tallyman:
+    status:
+      paid: PAID
+      overdue: OVERDUE
+      refunded: REFUNDED
+    invoice:
+      bill_to: "Bill To"
+      ship_to: "Ship To"
+      invoice_no: "Invoice number:"
+      receipt_no: "Receipt number:"
+      due_date: "Due Date:"
+      paid_date: "Paid Date:"
+      subtotal: "Subtotal:"
+      shipping: "Shipping:"
+      tax: "Tax:"
+      retention: "Retention:"
+      total: "Total:"
+      notes: "Notes:"
+    line_item:
+      description: Description
+      unit_price: "Unit Price"
+      quantity: Quantity
+      amount: Amount
+```
+
+If you translate the invoice into another language, a pull request adding your locale file is welcome.
+
+## Contributing
+
+Issues and pull requests are welcome on [GitHub](https://github.com/Rebase-Capital/tallyman). For anything larger than a small fix, open an issue first so that two people don't end up doing the same work.
+
+Run the specs and the linter with `bundle exec rake`.
+
+## History
+
+Tallyman is the continuation of [Payday](https://github.com/webtranslateit/payday), a gem written by Alan Johnson. When the original stopped working on Ruby 2.7 and its source was no longer on GitHub, we recovered the code from [rubygems.org](https://rubygems.org) and maintained it as `webtranslateit-payday`, adding features and fixes along the way. Tallyman 1.0.0 picks up where `webtranslateit-payday` 2.1.2 left off; the earlier history is in [Payday's repository](https://github.com/webtranslateit/payday) and its [changelog](https://github.com/webtranslateit/payday/blob/main/CHANGELOG.md).
+
+We use Tallyman at [WebTranslateIt.com](https://webtranslateit.com) and [Trackberry](https://trackberry.com) to generate invoices and receipts.
+
+Thanks to everyone who has contributed:
+
+* Alan Johnson, the original author
+* Sam Pizzey ([pizzeys](https://github.com/pizzeys))
+* Andrew Nordman ([cadwallion](https://github.com/cadwallion))
+* Pierre Olivier Martel ([pomartel](https://github.com/pomartel))
+* Matt Hoofman ([mhoofman](https://github.com/mhoofman))
+* Édouard Brière ([edouard](https://github.com/edouard))
+* Jim Jones ([aantix](https://github.com/aantix))
+* Hussein Morsy ([husseinmorsy](https://github.com/husseinmorsy))
+
+## Acknowledgements
+
+Tallyman 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
+
+Copyright (C) 2011 by Alan Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/config/locales/tallyman.de.yml

@@ -0,0 +1,24 @@
+de:
+  tallyman:
+    status:
+      overdue: ÜBERFÄLLIG
+      paid: BEZAHLT
+      refunded: ERSTATTET
+    invoice:
+      bill_to: Rechnung an
+      ship_to: Lieferadresse
+      invoice_no: "Rechnungsnr.:"
+      receipt_no: "Quittungsnr.:"
+      due_date: "Fälligkeit:"
+      paid_date: "Zahlungsdatum:"
+      subtotal: "Zwischensumme:"
+      shipping: "Versand:"
+      tax: "Steuern:"
+      retention: "Einbehalt:"
+      total: "Gesamt:"
+      notes: "Anmerkungen:"
+    line_item:
+      description: Beschreibung
+      unit_price: Stückpreis
+      quantity: Menge
+      amount: Betrag

data/config/locales/tallyman.en.yml

@@ -0,0 +1,24 @@
+en:
+  tallyman:
+    status:
+      paid: PAID
+      overdue: OVERDUE
+      refunded: REFUNDED
+    invoice:
+      bill_to: "Bill To"
+      ship_to: "Ship To"
+      invoice_no: "Invoice number:"
+      receipt_no: "Receipt number:"
+      due_date: "Due Date:"
+      paid_date: "Paid Date:"
+      subtotal: "Subtotal:"
+      shipping: "Shipping:"
+      tax: "Tax:"
+      retention: "Retention:"
+      total: "Total:"
+      notes: "Notes:"
+    line_item:
+      description: Description
+      unit_price: "Unit Price"
+      quantity: Quantity
+      amount: Amount

data/config/locales/tallyman.es.yml

@@ -0,0 +1,24 @@
+es:
+  tallyman:
+    status:
+      paid: PAGADO
+      overdue: VENCIDO
+      refunded: REEMBOLSADO
+    invoice:
+      bill_to: "Facturar a"
+      ship_to: "Enviar a"
+      invoice_no: "Número de factura proforma:"
+      receipt_no: "Número de factura:"
+      due_date: "Vencimiento:"
+      paid_date: "Fecha de pago:"
+      subtotal: "Subtotal:"
+      shipping: "Envío:"
+      tax: "Impuesto:"
+      retention: "Retención:"
+      total: "Total:"
+      notes: "Notas:"
+    line_item:
+      description: Descripción
+      unit_price: "Precio unitario"
+      quantity: Cantidad
+      amount: Importe

data/config/locales/tallyman.fr.yml

@@ -0,0 +1,24 @@
+fr:
+  tallyman:
+    status:
+      paid: PAYÉ
+      overdue: "EN RETARD"
+      refunded: "REMBOURSÉ"
+    invoice:
+      bill_to: "Adresse de facturation"
+      ship_to: "Adresse de livraison"
+      invoice_no: "Numéro de facture proforma :"
+      receipt_no: "Numéro de facture :"
+      due_date: "Date limite de paiement :"
+      paid_date: "Date de paiement :"
+      subtotal: "Sous-total :"
+      shipping: "Livraison :"
+      tax: "Taxes :"
+      retention: "Retenue :"
+      total: "Total :"
+      notes: "Notes :"
+    line_item:
+      description: Description
+      unit_price: "Prix unitaire"
+      quantity: Quantité
+      amount: Montant

data/config/locales/tallyman.nl.yml

@@ -0,0 +1,24 @@
+nl:
+  tallyman:
+    status:
+      paid: BETAALD
+      overdue: VERVALLEN
+      refunded: TERUGBETAALD
+    invoice:
+      bill_to: Factuuradres
+      ship_to: Afleveradres
+      invoice_no: "Factuurnummer:"
+      receipt_no: "Kwitantienummer:"
+      due_date: "Vervaldatum:"
+      paid_date: "Betaald op:"
+      subtotal: "Subtotaal:"
+      shipping: "Verzendkosten:"
+      tax: "Btw:"
+      retention: "Inhouding:"
+      total: "Totaal:"
+      notes: "Opmerkingen:"
+    line_item:
+      description: Omschrijving
+      unit_price: Eenheidsprijs
+      quantity: Aantal
+      amount: Bedrag

data/config/locales/tallyman.zh-CN.yml

@@ -0,0 +1,24 @@
+zh-CN:
+  tallyman:
+    status:
+      paid: 已付款
+      overdue: 已逾期
+      refunded: 已退款
+    invoice:
+      bill_to: 账单地址
+      ship_to: 送货地址
+      invoice_no: "发票号码:"
+      receipt_no: "收据号码:"
+      due_date: "到期日期:"
+      paid_date: "支付日期:"
+      subtotal: "小计:"
+      shipping: "运费:"
+      tax: "税费:"
+      retention: "扣缴:"
+      total: "总计:"
+      notes: "备注:"
+    line_item:
+      description: 描述
+      unit_price: 单价
+      quantity: 数量
+      amount: 金额

data/lib/generators/tallyman/setup/USAGE

@@ -0,0 +1,23 @@
+Description:
+    Creates the invoice and line item models Tallyman renders, and a migration
+    for their tables with every column Tallyman reads.
+
+    The models are called Invoice and LineItem unless you name them with
+    --invoice-name and --line-item-name. Names can be CamelCase or under_scored.
+
+    Names are singularized, as `rails generate model` does. Pass --force-plural
+    to keep a name such as Media exactly as you typed it.
+
+    Pass --skip-migration to generate the models only.
+
+Examples:
+    rails generate tallyman:setup
+
+        Creates the Invoice and LineItem models and a migration for the
+        invoices and line_items tables.
+
+    rails generate tallyman:setup --invoice-name=Bill --line-item-name=Charge
+
+        Creates the Bill and Charge models and a migration for the bills and
+        charges tables. A bill still reaches its charges through line_items,
+        which is the name Tallyman looks for.

data/lib/generators/tallyman/setup/setup_generator.rb

@@ -0,0 +1,75 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+# rails generate tallyman:setup [--invoice-name=Invoice] [--line-item-name=LineItem] [--skip-migration]
+#
+# Generates an invoice model, a line item model and the migration for their tables, with every
+# column Tallyman reads when it renders an invoice.
+module Tallyman
+  class SetupGenerator < Rails::Generators::Base
+    # Brings in next_migration_number, which follows the app's migration numbering settings.
+    include ActiveRecord::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    class_option :invoice_name, type: :string, default: "Invoice",
+                                desc: "Class name of the invoice model"
+    class_option :line_item_name, type: :string, default: "LineItem",
+                                  desc: "Class name of the line item model"
+    class_option :force_plural, type: :boolean, default: false,
+                                desc: "Keeps the model names as given instead of singularizing them"
+    class_option :skip_migration, type: :boolean, default: false,
+                                  desc: "Does not create the migration file for the tables"
+
+    def generate_invoice_model
+      template "invoice.rb", "app/models/#{invoice_class.underscore}.rb"
+    end
+
+    def generate_line_item_model
+      template "line_item.rb", "app/models/#{line_item_class.underscore}.rb"
+    end
+
+    def generate_migration
+      return if options.skip_migration?
+
+      migration_template "migration.rb", "db/migrate/#{migration_name}.rb"
+    end
+
+    private
+
+    def invoice_class
+      model_class(options.invoice_name)
+    end
+
+    def line_item_class
+      model_class(options.line_item_name)
+    end
+
+    # Singular, the way `rails generate model` would have it, unless --force-plural says the
+    # name is right as it stands: "Media" would otherwise come out as "Medium".
+    def model_class(name)
+      options.force_plural? ? name.camelize : name.camelize.singularize
+    end
+
+    # Named after the tables rather than after Tallyman, so the generator can be run again
+    # for a second pair of models without colliding with its first migration.
+    def migration_name
+      "create_#{invoice_table}_and_#{line_item_table}"
+    end
+
+    # A namespaced model reads the table named after its last segment unless its namespace sets
+    # a table_name_prefix, so Billing::Invoice gets "invoices".
+    def invoice_table
+      invoice_class.demodulize.tableize
+    end
+
+    def line_item_table
+      line_item_class.demodulize.tableize
+    end
+
+    # The name of the association from a line item back to its invoice, and so of its foreign key.
+    def invoice_reference
+      invoice_class.demodulize.underscore
+    end
+  end
+end

data/lib/generators/tallyman/setup/templates/invoice.rb

@@ -0,0 +1,7 @@
+class <%= invoice_class %> < ApplicationRecord
+  include Tallyman::Invoiceable
+
+  # Tallyman reads an invoice's lines through +line_items+, whatever the line item class is called.
+  has_many :line_items, class_name: "<%= line_item_class %>", foreign_key: :<%= invoice_reference %>_id,
+                        inverse_of: :<%= invoice_reference %>, dependent: :destroy
+end

data/lib/generators/tallyman/setup/templates/line_item.rb

@@ -0,0 +1,5 @@
+class <%= line_item_class %> < ApplicationRecord
+  include Tallyman::LineItemable
+
+  belongs_to :<%= invoice_reference %>, class_name: "<%= invoice_class %>", inverse_of: :line_items
+end

data/lib/generators/tallyman/setup/templates/migration.rb

@@ -0,0 +1,43 @@
+class <%= migration_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= invoice_table %> do |t|
+      t.string :invoice_number
+      t.text :bill_to
+      t.text :ship_to
+      t.text :notes
+
+      # tax_rate and retention_rate are percentages of the subtotal. shipping_rate is an amount.
+      t.decimal :tax_rate, precision: 8, scale: 4, default: 0, null: false
+      t.string :tax_description
+      t.decimal :shipping_rate, precision: 12, scale: 2, default: 0, null: false
+      t.string :shipping_description
+      t.decimal :retention_rate, precision: 8, scale: 4, default: 0, null: false
+      t.string :retention_description
+
+      # A due date in the past stamps the invoice OVERDUE, paid_at stamps it PAID and
+      # refunded_at stamps it REFUNDED.
+      t.date :due_at
+      t.date :paid_at
+      t.date :refunded_at
+
+      t.timestamps
+    end
+
+    create_table :<%= line_item_table %> do |t|
+      t.references :<%= invoice_reference %>, null: false, foreign_key: {to_table: :<%= invoice_table %>}
+
+      t.text :description
+      t.decimal :price, precision: 12, scale: 2, default: 0, null: false
+      t.decimal :quantity, precision: 12, scale: 3, default: 1, null: false
+
+      # A line with a predefined_amount is a flat fee: it shows no price or quantity.
+      t.decimal :predefined_amount, precision: 12, scale: 2
+
+      # Shown in place of the formatted price and quantity when set, "2 hours" for example.
+      t.string :display_price
+      t.string :display_quantity
+
+      t.timestamps
+    end
+  end
+end

data/lib/tallyman/appendix.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Tallyman
+
+  # Extra pages compiled onto the end of an invoice.
+  #
+  #   appendix = Tallyman::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 Tallyman'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/tallyman/config.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Tallyman
+
+  # Configuration for Tallyman. This is a singleton, so to set the company_name you would call
+  # Tallyman::Config.default.company_name = "Awesome Corp".
+  class Config
+
+    attr_accessor :invoice_logo, :company_name, :company_details, :date_format, :currency
+
+    # Sets the page size to use. Accepts the names '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
+    def self.default
+      @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.
+    def reset
+      # TODO: Move into specs and make minimal configuration required (company name / details)
+      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'
+      self.currency = 'USD'
+      self.page_size = 'LETTER'
+    end
+
+    # Internal: Contruct a new config object.
+    def initialize
+      reset
+    end
+
+  end
+
+end