verifiabl-issuer 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 136cf6c7ac5d993f41d75c2f441cbea8329aef35ae57edadc70d3530dc8850dc
-  data.tar.gz: e48d77fc6c7c06e77a4b58702bdd618dac3589a15428bbbc62abf5e3f3551821
+  metadata.gz: 619853ce9733f541d03c4f5267ff59da66383941256b56970953bfec703f6600
+  data.tar.gz: 2c3b3bb84032287482bbde88fca5e85c947b6f557da73e165f4c5a593e629d44
 SHA512:
-  metadata.gz: dd7911d0a278a7998ea615cfac226b999bfd386af07bfe4ab03628330711eb9568a61fe0ec0089f638c0f2602d9f5ff69897d9ceffbee4fe54fd8330fceb8e6b
-  data.tar.gz: 1543207b85bb2e61c53625fc2a610a9b99d4c0dc1b560165e79456725ab07000b62a8e7354dc2b817a44b7e53b13815373388b81480d53fa19ca5b6e3a7f6584
+  metadata.gz: a987cf173047507e67e5e693bcba5b59cbc914818261dddc1edfbeecf3cc5609a70f3db96e5da7b3a8e05f4aaf09ce6aab7acb22efe3665b622f1ab2a2a95f9f
+  data.tar.gz: 25180a6200be501ef89c6a647c0975018c14e7b34084c58ed8430e679a86f0fac38752f8c3591df56b8bda16a2084cf545f469f1ddb80eddcc23b76718dd4d36

data/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to the Verifiabl Ruby SDK will be documented in this file.
 
 ## Unreleased
 
+## [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
+
+- **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

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.5.0"
+gem "verifiabl-issuer", "1.0.0"
 ```
 
 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,9 @@ 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`.
 Printed-text fields such as `tax_code` and `pay_cycle` are not code sets.
 
 ### Self-managed barcode flow
@@ -244,14 +245,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 +321,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 +435,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/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": [
@@ -82,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

@@ -40,6 +40,10 @@ module Verifiabl
         PAY_FREQUENCIES = %w[
           weekly fortnightly monthly quarterly four_weekly semi_monthly
         ].map!(&:freeze).freeze
+
+        BASE_RATE_PERIODS = %w[
+          hour day week fortnight month year
+        ].map!(&:freeze).freeze
       end
 
       module NewZealand
@@ -62,6 +66,10 @@ module Verifiabl
         LEAVE_BALANCE_UNITS = %w[
           hours days weeks
         ].map!(&:freeze).freeze
+
+        BASE_RATE_PERIODS = %w[
+          hour day week fortnight month year
+        ].map!(&:freeze).freeze
       end
     end
   end

data/lib/verifiabl/issuer/non_pii_v2.rb

@@ -4,7 +4,8 @@ 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/
@@ -13,8 +14,20 @@ module Verifiabl
 
       def validate!(schema, payload)
         check!(FIELDS.fetch(schema), payload, "payslip_non_pii")
+        check_lump_sum_types!(payload) if schema == AUSTRALIAN_PAYSLIP_V2_SCHEMA
       end
 
+      # 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 check!(allowed, value, path)
         case allowed
         when Hash then check_object!(allowed, value, path)

data/lib/verifiabl/issuer/version.rb

@@ -2,6 +2,6 @@
 
 module Verifiabl
   module Issuer
-    VERSION = "0.5.0"
+    VERSION = "1.0.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verifiabl-issuer
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Verifiabl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-19 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: