verifiabl-issuer 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d049c2b4efee0761f9172022bee306456bc6e77d8223081196c027d289f88c48
-  data.tar.gz: b43694a8fa98216ddb558f3f63fc9c47f7a6c5740e6f47fd9c187a78f60fe437
+  metadata.gz: 38a29453b60641c65dce6fa59db036553e682fba8522515ff219292fd050a840
+  data.tar.gz: 0fefd2221e50f281d566c4e9288431f57e1f6516c9b3dbd1e0cf8907725a2121
 SHA512:
-  metadata.gz: 961b1387f5420386fa996309dfdf8c3b237879a6c350d31072a34a42d6a54bcc289f205fd81cae3a12da225a1f060b7fdebee1aa43ccc36ed1662b58c2a24682
-  data.tar.gz: 9f72f1055910e0725e340510d888fe8e271613c762cf72d39061fb9703b93d7b647af63d2558f45cbadf1832214736c0a2574d31caa338901d0cdb588f58a2a3
+  metadata.gz: b55577426409f44798777c70be3e21bff6f4280d072b9502bee0662f53dd0b43c98650d920f68ea1b120dc1450b43c8f5acfca4f7dbc076cf55e140a5798e16b
+  data.tar.gz: de6f5b281c1c0dbbb603e57d35e3896105a39d5758bf1c9effd6d4c79f28b82980f9ce757200403b095a78c96d79b243817fac8ff4c70056749977a3b9488fd9

data/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to the Verifiabl Ruby SDK will be documented in this file.
 
 ## Unreleased
 
+## [0.6.0] - 2026-10-13
+
+### Changed
+
+- **Breaking:** AU2 and NZ2 payloads replace `hourly` and `annual_rate` with
+  `base_rate`, the base rate the payslip prints apart from the earnings lines:
+  `{amount: "450.00", per: "day"}`. `per` is one of
+  `PayslipCodes::Australian::BASE_RATE_PERIODS` or
+  `PayslipCodes::NewZealand::BASE_RATE_PERIODS`. AU takes `hour`, `day` or
+  `year`; NZ also takes `week`. To migrate, send the printed annual rate as
+  `base_rate` with `per: "year"`, and a printed hourly rate as `base_rate`
+  with `per: "hour"`. Send hours and amounts only on `ordinary` earnings
+  lines. The API still accepts the old fields from earlier SDK versions.
+
+## [0.5.0] - 2026-10-09
+
+### Added
+
+- AU2 `lump_sum` earnings lines accept `lump_sum_type`
+  (`PayslipCodes::Australian::LUMP_SUM_TYPES`: `a_redundancy` for STP lump sum
+  A type R, `a_other` for A type T, `b`, `d` or `e`), and a new `etp` line takes
+  `etp_type` (`PayslipCodes::Australian::ETP_TYPES`: `redundancy` for ETP code
+  R, `other` for O, `redundancy_split` for S, `other_split` for P,
+  `death_dependant` for D, `death_non_dependant` for N,
+  `death_non_dependant_split` for B or `death_trustee` for T) and
+  `etp_component` (`PayslipCodes::Australian::ETP_COMPONENTS`: `taxable` or
+  `tax_free`). Send the taxable and tax-free components as separate `etp`
+  lines; tax withheld from an ETP is part of `paygw`. Lump sum W stays
+  `return_to_work`, and lump sum U stays `paid_leave` with
+  `unused_on_termination`. The gem sends a `lump_sum` line without a type, and
+  the API accepts that for now. It will require `lump_sum_type` before
+  production, once every issuer is on an SDK release with the lump sum codes.
+
+### Removed
+
+- **Breaking:** removed `au.payslip.v1` and `nz.payslip.v1` registration
+  validation. The gem no longer requires `period_start` for those schemas; it
+  sends them like any other schema without a field tree, and the issuer API
+  rejects them. Send `au.payslip.v2` instead, for example with
+  `Verifiabl::Issuer.prepare_australian_v2_payslip`.
+- **Breaking:** removed the P2 PII writer `Verifiabl::Issuer.format_pii`.
+  Verifiabl now accepts only the AU2 and NZ2 PII formats from issuers. Use
+  `prepare_australian_v2_payslip` or `prepare_new_zealand_v2_payslip`, or for
+  low-level use `format_australian_pii` or `format_new_zealand_pii` with
+  `encrypt_pii`. Payslips already issued with P1 or P2 still verify.
+
 ## [0.4.0] - 2026-10-07
 
 - Add `layout: :horizontal` to local SVG and PNG rendering, with the QR on the

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.4.0"
+gem "verifiabl-issuer", "0.6.0"
 ```
 
 Then run `bundle install`.
@@ -220,10 +220,12 @@ nz::LEAVE_BALANCE_UNITS # => ["hours", "days", "weeks"]
 ```
 
 `EARNINGS_TYPES`, `PAID_LEAVE_TYPES` and `ALLOWANCE_TYPES` are available for
-both jurisdictions. 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. Printed-text fields such as
-`tax_code` and `pay_cycle` are not code sets.
+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.
+Printed-text fields such as `tax_code` and `pay_cycle` are not code sets.
 
 ### Self-managed barcode flow
 
@@ -425,13 +427,16 @@ failures raise `TransportError`. Request and error messages never include the su
 
 ## Offline protocol primitives
 
-Format and encrypt PII locally. The plaintext must never be logged or sent to Verifiabl:
+Most integrations should use the v2 preparation helpers. To select the schema and formatter
+yourself, format and encrypt PII locally with `format_australian_pii` (AU2, for `au.payslip.v2`) or
+`format_new_zealand_pii` (NZ2, for `nz.payslip.v2`). The plaintext must never be logged or sent to
+Verifiabl:
 
 ```ruby
-plaintext = Verifiabl::Issuer.format_pii(
+plaintext = Verifiabl::Issuer.format_australian_pii(
   employee_name: "Jane Doe",
   employer_abn: "53004085616",
-  address: "12 Example St, Sydney NSW 2000"
+  address: {lines: ["12 Example St"], suburb: "Sydney", state_or_territory: "NSW", postcode: "2000"}
 )
 
 encrypted = Verifiabl::Issuer.encrypt_pii(plaintext, provider_encryption_key)

data/lib/verifiabl/issuer/generated/non-pii-v2-fields.json

@@ -13,12 +13,10 @@
     "employment_basis": null,
     "engagement_type": null,
     "award": null,
-    "hourly": {
-      "ordinary_rate": "decimal",
-      "hours": "decimal",
-      "amount": "decimal"
+    "base_rate": {
+      "amount": "decimal",
+      "per": null
     },
-    "annual_rate": "decimal",
     "taxable_gross": "decimal",
     "stsl_withholding": "decimal",
     "earnings": [
@@ -30,7 +28,10 @@
         "rate": "decimal",
         "ytd_amount": "decimal",
         "allowance_type": null,
-        "other_category": null
+        "other_category": null,
+        "lump_sum_type": null,
+        "etp_type": null,
+        "etp_component": null
       }
     ],
     "salary_sacrifice": [
@@ -79,12 +80,10 @@
     "tax_code": null,
     "employment_type": null,
     "hours_paid": "decimal",
-    "hourly": {
-      "ordinary_rate": "decimal",
-      "hours": "decimal",
-      "amount": "decimal"
+    "base_rate": {
+      "amount": "decimal",
+      "per": null
     },
-    "annual_rate": "decimal",
     "earnings_not_liable_for_acc": "decimal",
     "earnings": [
       {

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

@@ -7,8 +7,8 @@ module Verifiabl
     module PayslipCodes
       module Australian
         EARNINGS_TYPES = %w[
-          paid_leave allowance ordinary overtime bonus_commission directors_fees
-          lump_sum return_to_work other
+          paid_leave allowance lump_sum etp ordinary overtime
+          bonus_commission directors_fees return_to_work other
         ].map!(&:freeze).freeze
 
         PAID_LEAVE_TYPES = %w[
@@ -24,9 +24,26 @@ module Verifiabl
           home_office non_deductible transport_fares uniform private_vehicle general
         ].map!(&:freeze).freeze
 
+        LUMP_SUM_TYPES = %w[
+          a_redundancy a_other b d e
+        ].map!(&:freeze).freeze
+
+        ETP_TYPES = %w[
+          redundancy other redundancy_split other_split death_dependant death_non_dependant
+          death_non_dependant_split death_trustee
+        ].map!(&:freeze).freeze
+
+        ETP_COMPONENTS = %w[
+          taxable tax_free
+        ].map!(&:freeze).freeze
+
         PAY_FREQUENCIES = %w[
           weekly fortnightly monthly quarterly four_weekly semi_monthly
         ].map!(&:freeze).freeze
+
+        BASE_RATE_PERIODS = %w[
+          hour day year
+        ].map!(&:freeze).freeze
       end
 
       module NewZealand
@@ -49,6 +66,10 @@ module Verifiabl
         LEAVE_BALANCE_UNITS = %w[
           hours days weeks
         ].map!(&:freeze).freeze
+
+        BASE_RATE_PERIODS = %w[
+          hour day week year
+        ].map!(&:freeze).freeze
       end
     end
   end

data/lib/verifiabl/issuer/pii.rb

@@ -6,16 +6,12 @@ require_relative "generated/jurisdiction_pii_profiles"
 module Verifiabl
   module Issuer
     module Pii
-      FIELD_ORDER = %i[
-        employee_name position department employer_abn bsb account_number account_name address
-      ].freeze
       AUSTRALIAN_FIELD_ORDER = JurisdictionPiiProfiles::AUSTRALIAN_FIELD_ORDER
       NEW_ZEALAND_FIELD_ORDER = JurisdictionPiiProfiles::NEW_ZEALAND_FIELD_ORDER
-      PROFILE_ID = PiiTextProfile::PROFILE_ID
       AUSTRALIAN_PROFILE_ID = JurisdictionPiiProfiles::AUSTRALIAN_PROFILE_ID
       NEW_ZEALAND_PROFILE_ID = JurisdictionPiiProfiles::NEW_ZEALAND_PROFILE_ID
       PROFILE_UNICODE_VERSION = PiiTextProfile::UNICODE_VERSION
-      PAYLOAD_MAX_BYTES = PiiTextProfile::PAYLOAD_MAX_BYTES
+      PAYLOAD_MAX_BYTES = JurisdictionPiiProfiles::PAYLOAD_MAX_BYTES
       FORMAT_CHARACTER_RANGES = PiiTextProfile::FORMAT_CHARACTER_RANGES
 
       Violation = Data.define(:field, :reason)
@@ -43,16 +39,8 @@ module Verifiabl
 
       module_function
 
-      # Formats employee PII into the current P2 plaintext wire format. The
-      # returned value must be encrypted before it is persisted or embedded.
-      def format(fields)
-        validate_fields!(fields)
-        values, violations = normalize_values(fields)
-        raise ValidationError, violations unless violations.empty?
-
-        format_profile("P2", FIELD_ORDER.map { |field| values.fetch(field) })
-      end
-
+      # Formats Australian employee PII as AU2 plaintext. The returned value
+      # must be encrypted before it is persisted or embedded.
       def format_australian(fields)
         allowed = %i[
           employee_name position department employer_name employer_abn bsb account_number account_name address
@@ -69,6 +57,8 @@ module Verifiabl
         format_profile(JurisdictionPiiProfiles::AUSTRALIAN_MARKER, AUSTRALIAN_FIELD_ORDER.map { |field| wire_values.fetch(field) })
       end
 
+      # Formats New Zealand employee PII as NZ2 plaintext. The returned value
+      # must be encrypted before it is persisted or embedded.
       def format_new_zealand(fields)
         allowed = %i[
           employee_name ird_number position department employer_name account_number account_name address
@@ -83,7 +73,7 @@ module Verifiabl
         format_profile(JurisdictionPiiProfiles::NEW_ZEALAND_MARKER, NEW_ZEALAND_FIELD_ORDER.map { |field| wire_values.fetch(field) })
       end
 
-      def validate_fields!(fields, allowed = FIELD_ORDER)
+      def validate_fields!(fields, allowed)
         raise ArgumentError, "fields must be a Hash" unless fields.is_a?(Hash)
 
         normalized_keys = fields.keys.map do |key|
@@ -95,11 +85,6 @@ module Verifiabl
       end
       private_class_method :validate_fields!
 
-      def normalize_values(fields)
-        normalize_named_values(fields, FIELD_ORDER)
-      end
-      private_class_method :normalize_values
-
       def normalize_named_values(fields, names)
         names.each_with_object([{}, []]) do |field, (values, violations)|
           value, violation = normalize_value(field, field_value(fields, field))
@@ -155,8 +140,9 @@ module Verifiabl
 
       def format_profile(version, segments)
         plaintext = "#{version}|#{segments.join("|")}"
-        limit = (version == "P2") ? PAYLOAD_MAX_BYTES : JurisdictionPiiProfiles::PAYLOAD_MAX_BYTES
-        raise RangeError, "#{version} plaintext exceeds #{limit} UTF-8 bytes" if plaintext.bytesize > limit
+        if plaintext.bytesize > PAYLOAD_MAX_BYTES
+          raise RangeError, "#{version} plaintext exceeds #{PAYLOAD_MAX_BYTES} UTF-8 bytes"
+        end
 
         plaintext
       end

data/lib/verifiabl/issuer/validation.rb

@@ -57,9 +57,6 @@ module Verifiabl
 
       def validate_payslip_non_pii!(schema, payslip_non_pii)
         raise ArgumentError, "payslip_non_pii must be a Hash" unless payslip_non_pii.is_a?(Hash)
-        if %w[au.payslip.v1 nz.payslip.v1].include?(schema) && !key?(payslip_non_pii, :period_start)
-          raise ArgumentError, "period_start is required for #{schema}"
-        end
         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)

data/lib/verifiabl/issuer/version.rb

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

data/lib/verifiabl/issuer.rb

@@ -21,10 +21,6 @@ require_relative "issuer/version"
 module Verifiabl
   module Issuer
     class << self
-      def format_pii(fields)
-        Pii.format(fields)
-      end
-
       def format_australian_pii(fields)
         Pii.format_australian(fields)
       end

data/sig/verifiabl-issuer.rbs

@@ -11,6 +11,9 @@ module Verifiabl
         PAID_LEAVE_TYPES: Array[String]
         ALLOWANCE_TYPES: Array[String]
         OTHER_ALLOWANCE_CATEGORIES: Array[String]
+        LUMP_SUM_TYPES: Array[String]
+        ETP_TYPES: Array[String]
+        ETP_COMPONENTS: Array[String]
         PAY_FREQUENCIES: Array[String]
       end
 
@@ -57,7 +60,6 @@ module Verifiabl
       ?address: new_zealand_address?
     }
 
-    def self.format_pii: (Hash[Symbol | String, String?]) -> String
     def self.format_australian_pii: (australian_pii_fields) -> String
     def self.format_new_zealand_pii: (new_zealand_pii_fields) -> String
     def self.prepare_australian_v2_payslip: (pii: australian_pii_fields, payslip_non_pii: Hash[Symbol | String, untyped], issued_at: String | Time, key: binary, ?verifiabl_reference: String) -> PreparedV2Payslip

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verifiabl-issuer
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Verifiabl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64