verifiabl-issuer 0.6.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38a29453b60641c65dce6fa59db036553e682fba8522515ff219292fd050a840
-  data.tar.gz: 0fefd2221e50f281d566c4e9288431f57e1f6516c9b3dbd1e0cf8907725a2121
+  metadata.gz: b7c622f96124e2196fcc336d8295d30fef83a2efc296890d841aec4ef8376e50
+  data.tar.gz: c0e18b541a27073c6026703acd7e8eeae0b1ce6867f55f8d4847451b9eaef812
 SHA512:
-  metadata.gz: b55577426409f44798777c70be3e21bff6f4280d072b9502bee0662f53dd0b43c98650d920f68ea1b120dc1450b43c8f5acfca4f7dbc076cf55e140a5798e16b
-  data.tar.gz: de6f5b281c1c0dbbb603e57d35e3896105a39d5758bf1c9effd6d4c79f28b82980f9ce757200403b095a78c96d79b243817fac8ff4c70056749977a3b9488fd9
+  metadata.gz: d36cfeaf56c836a4cd99d5786697668664b9003bf15c3689a50034bb1e9285aa93675ace858eff1cab65b6033ee64bffb3656290a61bd9c11e643881aa83918e
+  data.tar.gz: dd8bd433cd88d3ab01373608eab57476afbb2770d922a4c0f22ea238dd8d0d2bd62a154a8aa30699785c68b3e8efb7a24dd0aaf93a9d2ae3b159cfeb9408bc64

data/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to the Verifiabl Ruby SDK will be documented in this file.
 
 ## Unreleased
 
+## [1.0.1] - 2026-10-20
+
+### Changed
+
+- AU2 and NZ2 codes may be Symbols, such as `currency: :AUD` or
+  `type: :lump_sum`. The gem converts them to Strings before its checks, so
+  every check treats both forms alike. Amounts must still be Strings.
+
+### Fixed
+
+- An AU2 earnings line with `type: :lump_sum` (a Symbol) and no
+  `lump_sum_type` now raises `ArgumentError`, as the String form already did.
+  1.0.0 sent it without the code.
+
+## [1.0.0] - 2026-10-19
+
+First stable release. The public API now follows Semantic Versioning.
+
+### Changed
+
+- **Breaking:** an AU2 `lump_sum` earnings line without a `lump_sum_type` now
+  raises `ArgumentError` before sending. The API still accepts the line from
+  older SDK versions. To migrate, send a `lump_sum_type` from
+  `PayslipCodes::Australian::LUMP_SUM_TYPES` on each lump sum.
+
+- `PayslipCodes::Australian::BASE_RATE_PERIODS` and
+  `PayslipCodes::NewZealand::BASE_RATE_PERIODS` both list every period a
+  payslip prints a rate in: `hour`, `day`, `week`, `fortnight`, `month` and
+  `year`.
+
+### Added
+
+- AU2 `superannuation` lines accept `contribution_type: "other"`, for an
+  employer contribution that is not SG, RESC or salary sacrifice, such as an
+  award or agreement rate above SG. `resc` excludes salary sacrifice, which has
+  its own `salary_sacrifice` line.
+
 ## [0.6.0] - 2026-10-13
 
 ### Changed

data/README.md

@@ -9,7 +9,7 @@ client, RBS signatures, and packed-gem consumer qualification.
 Add the stable release to your bundle:
 
 ```ruby
-gem "verifiabl-issuer", "0.6.0"
+gem "verifiabl-issuer", "1.0.1"
 ```
 
 Then run `bundle install`.
@@ -151,14 +151,14 @@ provider_encryption_key = Base64.strict_decode64(
 )
 prepared = Verifiabl::Issuer.prepare_australian_v2_payslip(
   pii: {
-    employee_name: "Jane A. Doe",
-    employer_name: "Example Payroll Pty Ltd",
+    employee_name: "Ana Leota",
+    employer_name: "Example Software Pty Ltd",
     employer_abn: "12 345 678 901",
-    address: {lines: ["A204/11-17 Eve Street"], suburb: "Erskineville", state_or_territory: "NSW", postcode: "2043"}
+    address: {lines: ["12 Example St"], suburb: "Sydney", state_or_territory: "NSW", postcode: "2000"}
   },
   payslip_non_pii: {
     period_end: "2026-05-31", payment_date: "2026-06-04", currency: "AUD",
-    gross: "8125.00", paygw: "2030.00", net: "6095.00"
+    gross: "9000.00", paygw: "2250.00", net: "6750.00"
   },
   issued_at: Time.now.utc,
   key: provider_encryption_key
@@ -223,8 +223,10 @@ nz::LEAVE_BALANCE_UNITS # => ["hours", "days", "weeks"]
 both jurisdictions. An AU2 `lump_sum` line takes a `lump_sum_type` from
 `LUMP_SUM_TYPES`, and an `etp` line takes an `etp_type` from `ETP_TYPES` and
 an `etp_component` from `ETP_COMPONENTS`. Use their strings in your normal
-payslip hash; the lists do not restrict input or add local enum/variant
-validation. The API may accept a new code before this gem is updated.
+payslip hash; the lists do not restrict input or add local enum validation,
+and the API may accept a new code before this gem is updated. The gem raises
+before sending an AU2 `lump_sum` line without a `lump_sum_type`. A code may
+also be a Symbol, such as `type: :lump_sum`; the gem sends it as a String.
 Printed-text fields such as `tax_code` and `pay_cycle` are not code sets.
 
 ### Self-managed barcode flow
@@ -244,14 +246,14 @@ require "verifiabl/issuer"
 PAYSLIP = {
   external_id: "PAY-1001",
   pii: {
-    employee_name: "Jane A. Doe",
+    employee_name: "Ana Leota",
     position: "Senior Developer",
     department: "Engineering",
-    employer_name: "Example Payroll Pty Ltd",
+    employer_name: "Example Software Pty Ltd",
     employer_abn: "12 345 678 901",
     bsb: "062-000",
     account_number: "****5678",
-    account_name: "Jane A Doe",
+    account_name: "A Leota",
     address: {lines: ["12 Example St"], suburb: "Sydney", state_or_territory: "NSW", postcode: "2000"}
   },
   non_pii: {
@@ -320,22 +322,22 @@ require "verifiabl/issuer"
 PAYSLIP = {
   external_id: "PAY-1002",
   pii: {
-    employee_name: "Zoë Nguyễn",
+    employee_name: "Ana Leota",
     ird_number: "***-***-***",
-    position: "Product Designer",
-    department: "Product",
-    employer_name: "Example Payroll NZ Ltd",
+    position: "Senior Developer",
+    department: "Engineering",
+    employer_name: "Example Software Limited",
     account_number: "**-****-*******-**",
-    account_name: "Zoë Nguyễn",
-    address: {lines: ["44 Harbour Rd"], suburb: "Parnell", city: "Auckland", postcode: "1052"}
+    account_name: "A Leota",
+    address: {lines: ["12 Example Street"], suburb: "Te Aro", city: "Wellington", postcode: "6011"}
   },
   non_pii: {
     period_end: "2026-08-31",
     payment_date: "2026-09-04",
     currency: "NZD",
-    gross: "7600.00",
-    paye: "1710.00",
-    net: "5890.00"
+    gross: "9000.00",
+    paye: "2283.96",
+    net: "6716.04"
   }
 }.freeze
 
@@ -434,7 +436,7 @@ Verifiabl:
 
 ```ruby
 plaintext = Verifiabl::Issuer.format_australian_pii(
-  employee_name: "Jane Doe",
+  employee_name: "Ana Leota",
   employer_abn: "53004085616",
   address: {lines: ["12 Example St"], suburb: "Sydney", state_or_territory: "NSW", postcode: "2000"}
 )

data/lib/verifiabl/issuer/generated/v2_codes.rb

@@ -42,7 +42,7 @@ module Verifiabl
         ].map!(&:freeze).freeze
 
         BASE_RATE_PERIODS = %w[
-          hour day year
+          hour day week fortnight month year
         ].map!(&:freeze).freeze
       end
 
@@ -68,7 +68,7 @@ module Verifiabl
         ].map!(&:freeze).freeze
 
         BASE_RATE_PERIODS = %w[
-          hour day week year
+          hour day week fortnight month year
         ].map!(&:freeze).freeze
       end
     end

data/lib/verifiabl/issuer/non_pii_v2.rb

@@ -4,56 +4,74 @@ require "json"
 
 module Verifiabl
   module Issuer
-    # A pre-transport guard for unknown fields and the decimal grammar, not a second implementation of the API contract.
+    # A pre-transport guard for unknown fields, the decimal grammar and AU2 lump sum codes, not a second
+    # implementation of the API contract.
     module NonPiiV2
       FIELDS = JSON.parse(File.read(File.join(__dir__, "generated/non-pii-v2-fields.json"))).freeze
       DECIMAL_PATTERN = /\A-?[0-9]+(?:\.[0-9]+)?\z/
 
       module_function
 
-      def validate!(schema, payload)
-        check!(FIELDS.fetch(schema), payload, "payslip_non_pii")
+      # Returns the payload with Symbol codes as Strings, so later checks see what JSON encoding sends.
+      def to_wire!(schema, payload)
+        wire = convert!(FIELDS.fetch(schema), payload, "payslip_non_pii")
+        check_lump_sum_types!(wire) if schema == AUSTRALIAN_PAYSLIP_V2_SCHEMA
+        wire
       end
 
-      def check!(allowed, value, path)
+      # The API still accepts a bare lump sum from older SDKs, but a lump sum without its STP2 code
+      # cannot be categorised, so this SDK requires the code before sending.
+      def check_lump_sum_types!(payload)
+        Array(payload["earnings"]).each_with_index do |line, index|
+          next unless line["type"] == "lump_sum" && line["lump_sum_type"].nil?
+
+          raise ArgumentError, "payslip_non_pii.earnings[#{index}].lump_sum_type is required on a lump_sum line"
+        end
+      end
+      private_class_method :check_lump_sum_types!
+
+      def convert!(allowed, value, path)
         case allowed
-        when Hash then check_object!(allowed, value, path)
-        when Array then check_array!(allowed.first, value, path)
-        when "decimal" then check_decimal!(value, path)
-        else check_scalar!(value, path)
+        when Hash then convert_object!(allowed, value, path)
+        when Array then convert_array!(allowed.first, value, path)
+        when "decimal" then decimal!(value, path)
+        else scalar!(value, path)
         end
       end
-      private_class_method :check!
+      private_class_method :convert!
 
-      def check_object!(allowed, value, path)
+      def convert_object!(allowed, value, path)
         raise ArgumentError, "#{path} must be an object" unless value.is_a?(Hash)
 
-        value.each do |key, child|
+        value.to_h do |key, child|
           raise ArgumentError, "#{path}.#{key} is not permitted" unless allowed.key?(key)
 
-          check!(allowed.fetch(key), child, "#{path}.#{key}")
+          [key, convert!(allowed.fetch(key), child, "#{path}.#{key}")]
         end
       end
-      private_class_method :check_object!
+      private_class_method :convert_object!
 
-      def check_array!(allowed, value, path)
+      def convert_array!(allowed, value, path)
         raise ArgumentError, "#{path} must be an array" unless value.is_a?(Array)
 
-        value.each_with_index { |child, index| check!(allowed, child, "#{path}[#{index}]") }
+        value.each_with_index.map { |child, index| convert!(allowed, child, "#{path}[#{index}]") }
       end
-      private_class_method :check_array!
+      private_class_method :convert_array!
 
-      def check_decimal!(value, path)
-        return if value.is_a?(String) && DECIMAL_PATTERN.match?(value)
+      # Amounts stay Strings only, so the SDK never guesses at a number's text.
+      def decimal!(value, path)
+        return value if value.is_a?(String) && DECIMAL_PATTERN.match?(value)
 
         raise ArgumentError, "#{path} must be a plain decimal String, for example \"1234.56\""
       end
-      private_class_method :check_decimal!
+      private_class_method :decimal!
 
-      def check_scalar!(value, path)
+      def scalar!(value, path)
         raise ArgumentError, "#{path} must be a scalar" if value.is_a?(Hash) || value.is_a?(Array)
+
+        value.is_a?(Symbol) ? value.to_s : value
       end
-      private_class_method :check_scalar!
+      private_class_method :scalar!
     end
   end
 end

data/lib/verifiabl/issuer/serialization.rb

@@ -12,7 +12,10 @@ module Verifiabl
       def registration_to_wire(schema:, issued_at:, payslip_non_pii:, encryption_metadata:)
         Validation.registration!(schema: schema, issued_at: issued_at, payslip_non_pii: payslip_non_pii, encryption_metadata: encryption_metadata)
         wire_payslip = stringify_keys(payslip_non_pii)
-        NonPiiV2.validate!(schema, wire_payslip) if [AUSTRALIAN_PAYSLIP_V2_SCHEMA, NEW_ZEALAND_PAYSLIP_V2_SCHEMA].include?(schema)
+        if [AUSTRALIAN_PAYSLIP_V2_SCHEMA, NEW_ZEALAND_PAYSLIP_V2_SCHEMA].include?(schema)
+          wire_payslip = NonPiiV2.to_wire!(schema, wire_payslip)
+          Validation.v2_currency!(wire_payslip)
+        end
         {
           "schema" => schema,
           "issued_at" => serialize_time(issued_at),

data/lib/verifiabl/issuer/validation.rb

@@ -14,7 +14,7 @@ module Verifiabl
 
       def registration!(schema:, issued_at:, payslip_non_pii:, encryption_metadata:)
         registration_envelope!(schema:, issued_at:, encryption_metadata:)
-        validate_payslip_non_pii!(schema, payslip_non_pii)
+        validate_payslip_non_pii!(payslip_non_pii)
       end
 
       def registration_envelope!(schema:, issued_at:, encryption_metadata:)
@@ -55,20 +55,19 @@ module Verifiabl
       end
       private_class_method :validate_encryption_metadata!
 
-      def validate_payslip_non_pii!(schema, payslip_non_pii)
+      def validate_payslip_non_pii!(payslip_non_pii)
         raise ArgumentError, "payslip_non_pii must be a Hash" unless payslip_non_pii.is_a?(Hash)
         validate_iso_date!(value(payslip_non_pii, :period_start), "period_start") if key?(payslip_non_pii, :period_start)
         validate_iso_date!(value(payslip_non_pii, :period_end), "period_end") if key?(payslip_non_pii, :period_end)
-        validate_v2_currency!(payslip_non_pii) if [AUSTRALIAN_PAYSLIP_V2_SCHEMA, NEW_ZEALAND_PAYSLIP_V2_SCHEMA].include?(schema)
       end
       private_class_method :validate_payslip_non_pii!
 
-      def validate_v2_currency!(payslip_non_pii)
-        return if SUPPORTED_V2_CURRENCIES.include?(value(payslip_non_pii, :currency))
+      # Takes the wire payslip, so a Symbol code has already become a String.
+      def v2_currency!(wire_payslip)
+        return if SUPPORTED_V2_CURRENCIES.include?(wire_payslip["currency"])
 
         raise ArgumentError, "currency is required and must be a supported ISO 4217 currency code, for example AUD"
       end
-      private_class_method :validate_v2_currency!
 
       def validate_issued_at!(issued_at)
         return if issued_at.is_a?(Time)

data/lib/verifiabl/issuer/version.rb

@@ -2,6 +2,6 @@
 
 module Verifiabl
   module Issuer
-    VERSION = "0.6.0"
+    VERSION = "1.0.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verifiabl-issuer
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Verifiabl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-13 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -206,7 +206,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/Verifiabl/verifiabl-ruby/issues
   changelog_uri: https://github.com/Verifiabl/verifiabl-ruby/blob/main/gems/verifiabl-issuer/CHANGELOG.md
-  documentation_uri: https://docs.verifiabl.io/payroll-providers
+  documentation_uri: https://docs.verifiabl.io/issuers
   homepage_uri: https://verifiabl.io
   source_code_uri: https://github.com/Verifiabl/verifiabl-ruby
 post_install_message: