tallyman 1.0.0

data/lib/tallyman/invoice.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Tallyman
+
+  # Basically just an invoice. Stick a ton of line items in it, add some details, and then render it out!
+  class Invoice
+
+    include Tallyman::Invoiceable
+
+    attr_accessor :invoice_number, :bill_to, :ship_to, :notes, :line_items, :shipping_description,
+                  :tax_description, :retention_description, :due_at, :paid_at, :refunded_at, :currency,
+                  :invoice_details, :invoice_date, :qr_code
+
+    attr_reader :tax_rate, :shipping_rate, :retention_rate
+
+    # 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.invoice_details = options[:invoice_details] || []
+    end
+
+    # The tax rate that we're applying, as a BigDecimal
+    def tax_rate=(value)
+      @tax_rate = Tallyman.to_decimal(value)
+    end
+
+    # Shipping rate
+    def shipping_rate=(value)
+      @shipping_rate = Tallyman.to_decimal(value)
+    end
+
+    # Retention rate (e.g. IRPF). Applied as a percentage of the subtotal and deducted from the total.
+    def retention_rate=(value)
+      @retention_rate = Tallyman.to_decimal(value)
+    end
+
+    # Adds a line item
+    def add_line_item(options = {})
+      line_items << Tallyman::LineItem.new(options)
+    end
+
+  end
+
+end

data/lib/tallyman/invoice_presenter.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Tallyman
+
+  # 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(setting(:date_format))
+    end
+
+    def t(key, default)
+      I18n.t("tallyman.#{key}", default: default)
+    end
+
+    def setting(property)
+      Tallyman::Config.default.value_for(@invoice, property)
+    end
+
+  end
+
+end

data/lib/tallyman/invoiceable.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Include {Tallyman::Invoiceable} in your Invoice class to make it Tallyman compatible. Tallyman
+# expects that a +line_items+ method containing an Enumerable of {Tallyman::LineItem} compatible
+# elements exists. Those LineItem objects primarily need to include quantity, price, and description methods.
+#
+# The +bill_to+ method should always be overwritten by your class. Otherwise, it'll say that your invoice should
+# be billed to Goofy McGoofison. +ship_to+ is also available, but will not be used in rendered invoices if it
+# doesn't exist.
+#
+# Although not required, if a +tax_rate+ method exists, {Tallyman::Invoiceable} will use it to calculate tax
+# 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).
+#
+# If the +due_at+, +paid_at+, and +refunded_at+ methods are available, {Tallyman::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 Tallyman
+
+  module Invoiceable
+
+    # Who the invoice is being sent to. A +bill_to+ the class already has wins over this
+    # placeholder: an ActiveRecord column reader sits behind this module in the ancestors, so
+    # without the +super+ a saved +bill_to+ would never be read.
+    def bill_to
+      return super if defined?(super)
+
+      "Goofy McGoofison\nYour Invoice Doesn't\nHave It's Own BillTo Method"
+    end
+
+    # Calculates the subtotal of this invoice by adding up all of the line items
+    def subtotal
+      line_items.reduce(BigDecimal(0)) { |result, item| result + item.amount }
+    end
+
+    # The tax for this invoice, as a BigDecimal
+    def tax
+      defined?(tax_rate) ? subtotal * tax_rate / 100 : 0
+    end
+
+    # TODO: Add a per weight unit shipping cost
+    # Calculates the shipping
+    def shipping
+      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
+      defined?(retention_rate) ? subtotal * retention_rate / 100 : 0
+    end
+
+    # Calculates the total for this invoice.
+    def total
+      subtotal + tax + shipping - retention
+    end
+
+    def overdue?
+      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?
+      defined?(refunded_at) && !!refunded_at
+    end
+
+    def paid?
+      defined?(paid_at) && !!paid_at
+    end
+
+    # Renders this invoice to pdf as a string. Pass a Tallyman::Appendix to compile pages of
+    # your own onto the end of it.
+    def render_pdf(appendix: nil)
+      Tallyman::PdfRenderer.render(self, appendix: appendix)
+    end
+
+    # Renders this invoice to pdf
+    def render_pdf_to_file(path, appendix: nil)
+      Tallyman::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 unless defined?(invoice_details)
+
+      invoice_details.each { |detail| yield detail[0], detail[1] }
+    end
+
+  end
+
+end

data/lib/tallyman/line_item.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Tallyman
+
+  # Represents a line item in an invoice.
+  #
+  # +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
+
+    attr_accessor :description, :display_quantity, :display_price
+    attr_reader :quantity, :price, :predefined_amount
+
+    # Initializes a new LineItem
+    def initialize(options = {})
+      if options[:predefined_amount]
+        self.predefined_amount = options[:predefined_amount]
+      else
+        self.quantity = options[:quantity] || '1'
+        self.display_quantity = options[:display_quantity]
+        self.display_price = options[:display_price]
+        self.price = options[:price] || '0.00'
+      end
+      self.description = options[:description] || ''
+    end
+
+    # Sets the quantity of this {LineItem}
+    def quantity=(value)
+      @quantity = Tallyman.to_decimal(value)
+    end
+
+    # Sets the price for this {LineItem}
+    def price=(value)
+      @price = Tallyman.to_decimal(value)
+    end
+
+    # Sets the predefined_amount for this {LineItem}
+    def predefined_amount=(value)
+      @predefined_amount = Tallyman.to_decimal(value)
+    end
+
+  end
+
+end

data/lib/tallyman/line_itemable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Include this module into your line item implementation to make sure that Tallyman stays happy
+# with it, or just make sure that your line item implements the amount method.
+module Tallyman
+
+  module LineItemable
+
+    # Returns the total amount for this {LineItemable}, or +price * quantity+
+    def amount
+      return predefined_amount if predefined_amount
+
+      price * quantity
+    end
+
+  end
+
+end

data/lib/tallyman/markup.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Tallyman
+
+  # Converts the Prawn +inline_format+ markup this gem 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

data/lib/tallyman/pdf_renderer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Tallyman
+
+  # Renders an invoice to PDF by feeding a presented Hash to the Typst template.
+  #
+  # Invoice data crosses into the template only as sys_inputs JSON, where Typst treats every
+  # string as literal text. Never interpolate invoice data into the template source.
+  class PdfRenderer
+
+    TEMPLATE = File.expand_path('templates/invoice.typ', __dir__)
+    FONT_DIR = File.expand_path('../../fonts', __dir__)
+    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, appendix: nil)
+      File.binwrite(path, render(invoice, appendix: appendix))
+    end
+
+    # Renders the given invoice as a pdf, returning a string. See Tallyman::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(Tallyman::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 initialize(invoice, appendix: nil)
+      @invoice = invoice
+      @appendix = Appendix.wrap(appendix)
+      @dependencies = {}
+    end
+
+    def render
+      data = InvoicePresenter.new(@invoice).to_h
+      register_qr_code(data[:qr_code])
+      data[:logo] = logo
+
+      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 = Tallyman::Config.default.value_for(@invoice, :invoice_logo)
+      return nil if setting.nil?
+
+      path, width, height = logo_parts(setting)
+      name = "logo#{File.extname(path.to_s)}"
+      @dependencies[name] = File.binread(path.to_s)
+      {name: name, width: width, height: height}
+    end
+
+    def logo_parts(setting)
+      return [setting, nil, nil] unless setting.is_a?(Hash)
+
+      width, height = setting[:size].to_s.split('x').map(&:to_f)
+      [setting[:filename], width, height]
+    end
+
+    def register_qr_code(data)
+      return if data.nil?
+
+      @dependencies['qr.svg'] = QrCode.new(data).to_svg
+    end
+
+  end
+
+end

data/lib/tallyman/qr_code.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'rqrcode'
+
+module Tallyman
+
+  # Draws a QR code as an SVG.
+  #
+  # The matrix comes straight from RQRCode, so the payload and its error correction level are
+  # untouched and the code carries exactly the same data it always did. Only the drawing
+  # changes: vector instead of a 200px raster, lightly rounded modules, and the three finder
+  # patterns drawn as rounded frames.
+  #
+  # Rounding is kept deliberately slight. These codes are scanned off paper, sometimes off a
+  # bad photocopy, and on a Verifactu invoice a code that will not scan is a compliance
+  # problem rather than a cosmetic one. Modules keep their full square footprint apart from a
+  # softened corner, so a scanner sees the same geometry the old raster produced.
+  class QrCode
+
+    QUIET_ZONE = 4    # modules of clear space; the QR spec's minimum
+    UNIT = 10         # user units per module
+    RADIUS = 1.5      # corner radius of a data module, out of UNIT
+    FINDER = 7        # finder patterns are 7 modules square
+    # Corner radius of a finder frame. Above roughly 1.2 modules the curve starts cutting the
+    # corner module out of the ring, which changes what a scanner reads.
+    EYE_RADIUS = 10
+    DARK = '#111111'
+    LIGHT = '#ffffff'
+
+    def initialize(data)
+      @modules = RQRCode::QRCode.new(data.to_s).modules
+    end
+
+    def to_svg
+      <<~SVG
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{side} #{side}" shape-rendering="geometricPrecision">
+        <rect width="#{side}" height="#{side}" fill="#{LIGHT}"/>
+        #{(data_modules + finders).join("\n")}
+        </svg>
+      SVG
+    end
+
+    private
+
+    def size
+      @modules.length
+    end
+
+    def side
+      (size + (QUIET_ZONE * 2)) * UNIT
+    end
+
+    def data_modules
+      @modules.each_with_index.flat_map do |cells, row|
+        cells.each_with_index.filter_map do |dark, col|
+          module_rect(row, col) if dark && !finder?(row, col)
+        end
+      end
+    end
+
+    def module_rect(row, col)
+      %(<rect class="m" x="#{x(col)}" y="#{x(row)}" width="#{UNIT}" height="#{UNIT}" ) +
+        %(rx="#{RADIUS}" fill="#{DARK}"/>)
+    end
+
+    # A finder is a 7x7 ring with a 3x3 centre. Drawing it as two rounded rects rather than 33
+    # separate modules is what gives the code its softer corners.
+    def finders
+      finder_origins.flat_map { |row, col| [ring(row, col), pupil(row, col)] }
+    end
+
+    def ring(row, col)
+      %(<rect class="f" x="#{x(col) + (UNIT / 2)}" y="#{x(row) + (UNIT / 2)}" ) +
+        %(width="#{UNIT * 6}" height="#{UNIT * 6}" rx="#{EYE_RADIUS}" ) +
+        %(fill="none" stroke="#{DARK}" stroke-width="#{UNIT}"/>)
+    end
+
+    def pupil(row, col)
+      %(<rect class="p" x="#{x(col + 2)}" y="#{x(row + 2)}" ) +
+        %(width="#{UNIT * 3}" height="#{UNIT * 3}" rx="#{UNIT}" fill="#{DARK}"/>)
+    end
+
+    def finder_origins
+      [[0, 0], [0, size - FINDER], [size - FINDER, 0]]
+    end
+
+    def finder?(row, col)
+      finder_origins.any? do |r, c|
+        row.between?(r, r + FINDER - 1) && col.between?(c, c + FINDER - 1)
+      end
+    end
+
+    def x(index)
+      (index + QUIET_ZONE) * UNIT
+    end
+
+  end
+
+end