einvoice 1.3 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8073afaa58225b965eeed8fb135712ab8b1b76c95b759324f35e875bf9eacb32
-  data.tar.gz: ed9440ffcba86cdbf84e98b0030fb3e53c9e1b7418551c99cd102639c4921712
+  metadata.gz: 0ce2293f378b646e5ae9ab94d5cce8b539a7dd441d8db03472ae3c6f4bbd9735
+  data.tar.gz: 0d8e775b71d10cb37f3892cc40bd8e46e1ce872721ec7cb1c0864807d6a5f24d
 SHA512:
-  metadata.gz: f0d297e2b70749e83b4ebf531ee49597d72ee6404a295eb3abd03c6e68e06da500cbbdfc6fe556fb8be761786b1ef4a9b11626e7e5758eda12f0cbf13420ba1d
-  data.tar.gz: 75ca49a608cbd45bcc1fdc8575183d98ab079ec18684e073da6e944fc77f63eaa072e9e87d32e360ee8bda102dcccc9ed9b01fb3853d7a842d67368cd7de0f48
+  metadata.gz: 233c9f4194869b5e61420c7b255f768befe0f09cb3f952f1c300c7d9b8e417d98053461f1b794cf5f7a9a7c4b4a428b38b99db0005e77429d9686bf3afad1bda
+  data.tar.gz: 11f5ba7e0132eb0dc9eb4d0fc16cd48252b950b3c189f2c45efa4757bfbc43936c3c97155692d2e3b989bf038e528e20f5ee023031817fed9ab0a3a7bbb564d7

data/.coderabbit.yaml

@@ -0,0 +1,14 @@
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  auto_review:
+    enabled: true
+    drafts: false
+  path_filters:
+    - "!lib/einvoice/donation_unit_list.json"
+  path_instructions:
+    - path: "lib/einvoice/tradevan/**"
+      instructions: >
+        This is legacy 1.x code kept for backward compatibility.
+        Do not suggest large-scale refactors or architecture changes here.
+        Focus only on correctness bugs and security issues.

data/.github/workflows/build.yml

@@ -2,9 +2,9 @@ name: build
 
 on:
   push:
-    branches: [ main ]
+    branches: [ 1-x-stable ]
   pull_request:
-    branches: [ main ]
+    branches: [ 1-x-stable ]
 
 permissions:
   contents: read
@@ -16,7 +16,7 @@ jobs:
         ruby-version: ['3.1', '3.2', '3.3', '3.4']
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -30,7 +30,10 @@ jobs:
       - name: Run tests
         run: bundle exec rspec
 
-      - name: Publish code coverage
-        uses: paambaati/codeclimate-action@v9
-        env:
-          CC_TEST_REPORTER_ID: 134e1f1cc8b60db4f2a491152c9227a6dbbfbeba5c1d05ee8b44cd78a1069f28
+      - name: Upload coverage to Codecov
+        if: matrix.ruby-version == '3.4'
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/lcov.info
+          fail_ci_if_error: true

data/.github/workflows/cron.yml

@@ -2,17 +2,30 @@ name: Daily update
 on:
   schedule:
     - cron: 0 0 * * *
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
 jobs:
   build:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: actions/setup-ruby@v1
-    - name: bundle and run rake update
+    - uses: actions/checkout@v4
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.3'
+        bundler-cache: true
+    - name: Update donation unit list
+      run: bundle exec rake update_donation_unit
+    - name: Commit and push changes
       run: |
-        bundle install --jobs 4 --retry 3
-        bundle exec rake update_donation_unit
-    - uses: mikeal/publish-to-github-action@master
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        BRANCH_NAME: 'main'
+        if git diff --quiet; then
+          echo "Donation unit list is up to date"
+          exit 0
+        fi
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git add lib/einvoice/donation_unit_list.json
+        git commit -m "Automated donation unit list update"
+        git push

data/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.5.0] - 2026-09-11
+
+### Fixed
+- Tradevan `IssueData#payload` and `VoidData#payload` now exclude
+  `context_for_validation`. On Rails 8 this internal ivar was sent as a
+  business field once `valid?` had run, and Tradevan rejected the whole
+  request. Thanks @dlackty.
+
+### Changed
+- **Ruby 3.1 or newer is now required.** CI covers 3.1 through 3.4.
+- **Faraday 2 is now required** (`~> 2.1`); `faraday_middleware` is gone,
+  replaced by a built-in `Faraday::Response::ParseXml`. If you pin
+  `faraday` to 1.x, stay on 1.4.0.
+- `Einvoice::Utils` and the `gyoku` dependency have been removed. Nothing
+  in the gem called them.
+
+### Internal
+- Added request-level Tradevan provider specs.
+- CI runs on `1-x-stable`; the donation unit list task parses with `CSV`.
+- README documents the allowance operations and 1.x maintenance mode.
+
+## [1.4.0] - 2026-08-08
+
+### Changed
+- **TLS certificate verification is now enabled by default.** Previously every
+  request was sent with `ssl: { verify: false }`, regardless of configuration.
+  If you were relying on that behavior (e.g. against an endpoint with an
+  incomplete certificate chain), set `config.ssl_verify = false` or pass
+  `ssl_verify: false` to `Provider.new` to restore the old behavior.
+- `Client` now delegates to the provider via `public_send` instead of `send`,
+  and implements `respond_to_missing?`. Private provider methods (e.g.
+  `encrypt`, `connection`) are no longer reachable through `Client`.
+
+### Fixed
+- `TotalValidator` comparison was inverted and compared a `String` against an
+  `Integer`, so it never actually validated anything. It now correctly fails
+  when `total` doesn't match the sum of item totals.
+- `AllowanceNumberValidator` and `IssueItem#invoiceTime`'s format regexp had
+  broken escape sequences (`\A` and `\d` collapsing to literal characters in a
+  double-quoted string), causing them to reject all valid input.
+- `ItemListValidator` pushed directly onto `record.errors[:itemList]`, which
+  is deprecated in Rails 6.1 and removed in 7.0. It now uses `errors.add` and
+  actually registers errors again.
+- Tradevan response decoding used `JSON.load`, which is unsafe for untrusted
+  input. Switched to `JSON.parse`.
+- `lib/einvoice/donation_unit_list.json` was stale since 2023-12 (the
+  scheduled update workflow had been silently broken), causing
+  `DonationUnitValidator` to reject currently valid donation codes and accept
+  retired ones. The list has been refreshed (~340 entries changed).
+
+### Added
+- Specs for `Client` delegation, `Configuration#ssl_verify`,
+  `Provider#connection` SSL behavior, the validator fixes above, and the
+  previously-untested `decode_tradevan` middleware.
+
+### Internal
+- CI coverage reporting migrated from Code Climate (discontinued) to Codecov.
+- The scheduled `cron.yml` workflow that refreshes the donation unit list
+  has been repaired — it depended on two archived GitHub Actions
+  (`actions/setup-ruby`, `mikeal/publish-to-github-action`) and hadn't run
+  successfully since 2023-12.
+
+---
+
+Versions prior to 1.4.0 were not tracked in this file. See the
+[release history](https://github.com/abookyun/einvoice/releases) and
+[commit log](https://github.com/abookyun/einvoice/commits/main/) for earlier changes.

data/Gemfile

@@ -3,7 +3,14 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in einvoice.gemspec
 gemspec
 
-# Integrate CodeClimate Code Coverage into TravisCI
-# https://github.com/codeclimate/test-reporter/issues/413
-gem 'simplecov', require: false, group: :test
-gem "simplecov_json_formatter", require: false, group: :test
+# Remove this pin once we drop Ruby 3.1 support. json 3.0 dropped quirks_mode,
+# which activesupport 7.2.3.2 still passes; 7.2.3.2 is the newest activesupport
+# that works on Ruby 3.1.
+gem "json", "< 3.0"
+
+# Used by the update_donation_unit rake task; csv leaves the default gems in Ruby 3.4.
+gem "csv", require: false, group: :development
+
+gem "ostruct", require: false, group: :development
+gem "simplecov", require: false, group: :test
+gem "simplecov-lcov", require: false, group: :test

data/README.md

@@ -1,7 +1,11 @@
 # Einvoice
 [![Build Status](https://github.com/abookyun/einvoice/actions/workflows/build.yml/badge.svg)](https://github.com/abookyun/einvoice/actions/workflows/build.yml)
-[![Code Climate](https://codeclimate.com/github/abookyun/einvoice/badges/gpa.svg)](https://codeclimate.com/github/abookyun/einvoice)
-[![Test Coverage](https://codeclimate.com/github/abookyun/einvoice/badges/coverage.svg)](https://codeclimate.com/github/abookyun/einvoice/coverage)
+[![codecov](https://codecov.io/github/abookyun/einvoice/graph/badge.svg?token=yxJNmXiUyp)](https://codecov.io/github/abookyun/einvoice)
+
+> **The 1.x line is moving to maintenance mode.** A provider-agnostic 2.0
+> rewrite is in progress on `main`; once it lands, 1.x continues on the
+> [`1-x-stable`](https://github.com/abookyun/einvoice/tree/1-x-stable) branch.
+> If you depend on the current Tradevan client, pin `~> 1.4`.
 
 ## What's E-Invoice
 
@@ -42,8 +46,25 @@ Einvoice.configure do |config|
   config.client_secret = ENV['EINVOICE_CLIENT_SECRET']
   config.encryption_keys = ENV['ENCRYPTION_KEYS']
   config.format = "json"
+  # config.ssl_verify = false # disable TLS certificate verification (default: true)
 end
 ```
+### SSL certificate verification
+
+By default, `einvoice` verifies the TLS certificate of the configured
+endpoint (`config.ssl_verify` defaults to `true`). If you need to disable
+this — for example when testing against an endpoint with an incomplete
+certificate chain — you can opt out:
+
+```ruby
+config.ssl_verify = false
+```
+
+Or per-provider:
+
+```ruby
+Einvoice::Tradevan::Provider.new(ssl_verify: false)
+```
 
 ### Initialize
 
@@ -51,7 +72,7 @@ end
 client = Einvoice::Client.new(Einvoice::Tradevan::Provider.new)
 ```
 
-### Issue an invoice
+### Issue an invoice (開立電子發票)
 
 ```ruby
 payload = {
@@ -122,7 +143,7 @@ result.data
 # }
 ```
 
-### Cancel an invoice
+### Cancel an invoice (作廢電子發票)
 
 ```ruby
 payload = {
@@ -149,7 +170,74 @@ result.data
 # }
 ```
 
-### Search invoice by memberId/memberId/sellTargetCode
+### Issue an allowance (開立折讓單)
+
+An allowance against a previously issued invoice is sent through `issue` with `type: "A"`. Each item must reference the original invoice (`invoiceNumber` / `invoiceDate`) and carry its tax-exclusive amount (`itemExclude`).
+
+```ruby
+payload = {
+  companyUn: "12345678",
+  orgId: "ABCDE",
+  type: "A",
+  allowanceIdentifier: "12345678_ABCDE_53b2a44e4b3d",
+  transactionNumber: "53b2a44e4b3d",
+  transactionDate: "20160426",
+  paperPrintMode: "0",
+  invoiceAlarmMode: "4",
+  allowanceExclusiveAmount: "95",
+  allowanceTax: "5",
+  allowanceInclusiveAmount: "100",
+  allowancePaperReturned: "N",
+  invoicePaperReturned: "N",
+  receiverName: "John Appleseed",
+  receiverEmail: "john@gmail.com",
+  itemList: [
+    {
+      saleIdentifier: "12345678_ABCDE_53b2a44e4b3c",
+      serialNumber: "0001",
+      invoiceNumber: "GX38551078",
+      invoiceDate: "20160425",
+      productName: "Coffee Latte",
+      qty: "1000",
+      price: "100",
+      itemExclude: "95",
+      tax: "5",
+      itemTotal: "100",
+      taxType: "T"
+    }
+  ]
+}
+```
+
+```ruby
+result = client.issue(payload)
+result.successful?
+#=> true
+```
+
+Notes:
+
+* `allowanceIdentifier` must be prefixed with `"#{companyUn}_#{orgId}_"`, like `saleIdentifier` on invoices.
+* `allowanceExclusiveAmount` + `allowanceTax` = `allowanceInclusiveAmount`.
+
+### Void an allowance (作廢折讓單)
+
+```ruby
+payload = {
+  type: "A",
+  companyUn: "12345678",
+  allowanceNumber: "ABCDE20160426001",
+  allowancePaperReturned: "Y",
+}
+```
+
+```ruby
+result = client.cancel(payload)
+result.successful?
+#=> true
+```
+
+### Search invoice by memberId/sellTargetCode (載具/會員發票查詢)
 
 ```ruby
 payload = {
@@ -195,7 +283,7 @@ result.data
 # ]
 ```
 
-### Search invoice detail
+### Search invoice detail (發票開立明細查詢)
 
 ```ruby
 result = client.search_invoice_detail("GX38551078")
@@ -239,7 +327,7 @@ result.data
 # }
 ```
 
-### Send card info to customer
+### Send card info to customer (電子發票載具歸戶/中獎通知作業)
 
 ```ruby
 payload = {
@@ -259,7 +347,7 @@ result.successful?
 result.data
 ```
 
-### Get invoice mark info
+### Get invoice mark info (電子發票字軌號碼配額取號/分配作業)
 
 ```ruby
 payload = {
@@ -291,13 +379,13 @@ result.data
 # ]
 ```
 
-### Get donate unit list
+### Get donate unit list (受贈機關/社福團體愛心碼清單查詢)
 
 ```ruby
 client.get_donate_unit_list("12345678")
 ```
 
-### Get invoice content
+### Get invoice content (電子發票內容查詢)
 
 ```ruby
 payload = {

data/Rakefile

@@ -7,13 +7,51 @@ task default: :spec
 
 desc "Download latest e-invoice donation unit list and convert it to JSON"
 task :update_donation_unit do
+  require "csv"
   require "json"
   require "faraday"
+
   # From https://data.gov.tw/dataset/31868
-  data = Faraday.get("https://dataset.einvoice.nat.gov.tw/ods/portal/ODS303W/download/3886F055-EB77-4DF9-98E2-F3F49A7D3434/1/8B227A99-042A-4903-8B34-5715442A227D/0/?fileType=csv").body.force_encoding("utf-8")
-  orgs = data.split("\n")[1..-1].map do |line|
-    line.split(",").values_at(2, 1)
-  end.sort_by(&:first)
+  url = "https://dataset.einvoice.nat.gov.tw/ods/portal/ODS303W/download/3886F055-EB77-4DF9-98E2-F3F49A7D3434/1/8B227A99-042A-4903-8B34-5715442A227D/0/?fileType=csv"
+  response = Faraday.get(url)
+  raise "Download failed: HTTP #{response.status}" unless response.status == 200
+
+  body = response.body
+
+  possible = ["UTF-8", "Big5"]
+  chosen = nil
+  utf8_text = nil
+
+  possible.each do |code|
+    begin
+      str = body.dup.force_encoding(code)
+      candidate = str.encode("UTF-8")
+      if candidate.valid_encoding?
+        chosen = code
+        utf8_text = candidate
+        break
+      end
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      next
+    end
+  end
+
+  unless chosen
+    chosen = "fallback(replace)"
+    utf8_text = body.dup.force_encoding("UTF-8").scrub("?")
+    puts "::warning::Used fallback encoding with replacement; some characters may be lost"
+  end
+
+  utf8_text = utf8_text.delete_prefix("\uFEFF") # remove possible UTF-8 BOM
+  csv = CSV.parse(utf8_text, headers: true)
+
+  orgs = csv.map do |row|
+    code = (row['捐贈碼'] || row[2]).to_s.strip
+    name = (row['受捐贈機關或團體名稱'] || row[1]).to_s.strip
+    [code, name]
+  end.sort_by { |code, _| [code.to_i, code] }
+
+  File.write "lib/einvoice/donation_unit_list.json", JSON.pretty_generate(orgs.to_h)
 
-  File.write "lib/einvoice/donation_unit_list.json", JSON.pretty_generate(Hash[orgs])
-end
+  puts "Wrote lib/einvoice/donation_unit_list.json (#{orgs.length} entries)"
+end

data/einvoice.gemspec

@@ -9,25 +9,30 @@ Gem::Specification.new do |spec|
   spec.authors       = ["David Yun"]
   spec.email         = ["abookyun@gmail.com"]
 
-  spec.summary       = %q{A API wrapper for Taiwan e-invoice services.}
+  spec.summary       = %q{An API wrapper for Taiwan e-invoice services.}
   spec.homepage      = "https://github.com/abookyun/einvoice"
   spec.license       = "MIT"
 
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/abookyun/einvoice",
+    "changelog_uri" => "https://github.com/abookyun/einvoice/blob/main/CHANGELOG.md",
+    "bug_tracker_uri" => "https://github.com/abookyun/einvoice/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = '>= 2.0.0'
-  spec.add_dependency "faraday"
-  spec.add_dependency "faraday_middleware"
+  spec.required_ruby_version = '>= 3.1'
+  spec.add_dependency "faraday", "~> 2.1"
   spec.add_dependency "multi_xml"
   spec.add_dependency "activemodel"
   spec.add_dependency "activesupport"
-  spec.add_dependency "gyoku"
 
   spec.add_development_dependency "bundler", "> 1.17"
-  spec.add_development_dependency "rake", "~> 12.3"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "factory_bot"

data/lib/einvoice/client.rb

@@ -7,7 +7,15 @@ module Einvoice
     end
 
     def method_missing(m, *args, &block)
-      provider.send(m, *args, &block)
+      if provider.respond_to?(m)
+        provider.public_send(m, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(m, include_private = false)
+      provider.respond_to?(m) || super
     end
   end
 end

data/lib/einvoice/configuration.rb

@@ -8,7 +8,8 @@ module Einvoice
       :client_id,
       :client_secret,
       :encryption_keys,
-      :format
+      :format,
+      :ssl_verify
     ].freeze
 
     DEFAULT_CLIENT_ID = nil
@@ -17,8 +18,9 @@ module Einvoice
     DEFAULT_ENDPOINT_URL = nil
     DEFAULT_FORMAT = ""
     DEFAULT_ENCRYPTION_KEYS = {}
+    DEFAULT_SSL_VERIFY = true
 
-    attr_accessor *VALID_OPTIONS_KEYS
+    attr_accessor(*VALID_OPTIONS_KEYS)
 
     def self.extended(base)
       base.reset
@@ -41,6 +43,7 @@ module Einvoice
       self.endpoint_url    = DEFAULT_ENDPOINT_URL
       self.encryption_keys = DEFAULT_ENCRYPTION_KEYS
       self.format          = DEFAULT_FORMAT
+      self.ssl_verify      = DEFAULT_SSL_VERIFY
     end
   end
 end

data/lib/einvoice/connection.rb

@@ -1,5 +1,5 @@
-require "faraday_middleware"
 require "faraday/response/decode_tradevan"
+require "faraday/response/parse_xml"
 
 module Einvoice
   module Connection
@@ -8,7 +8,8 @@ module Einvoice
     def connection(options = {})
       connection_options = {
         headers: { "Accept" => "application/#{format}; charset=utf-8" },
-        url: endpoint
+        url: endpoint,
+        ssl: { verify: ssl_verify != false }
       }.merge(options)
 
       ::Faraday::Connection.new(connection_options) do |connection|