einvoice 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2393870fedb2a46c8a29d7c903b109080499b621904e46d45b505c33e8e3147c
-  data.tar.gz: c8ad7c8e9e6674887af0458bc00ed362e182ad39a2d30d7a4624f537e96e1c0d
+  metadata.gz: 0ce2293f378b646e5ae9ab94d5cce8b539a7dd441d8db03472ae3c6f4bbd9735
+  data.tar.gz: 0d8e775b71d10cb37f3892cc40bd8e46e1ce872721ec7cb1c0864807d6a5f24d
 SHA512:
-  metadata.gz: d44581204a25dcd2f434510535ae5d5803263310ecbb6431590c5c9bc7398a10e63c0d9391c12d86417a2040cc5031c884fba915e7015c394ff32e14ed880801
-  data.tar.gz: 4076e9ef62d58aba07a0261dfee0b989d58a6eb41ade8b582e1770fde2f1f709e7a6308260a6b3312221454b1e97651489343cfc63beba4d8e86d9189868a10e
+  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:

data/CHANGELOG.md

@@ -5,6 +5,27 @@ 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

data/Gemfile

@@ -3,6 +3,14 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in einvoice.gemspec
 gemspec
 
+# 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

@@ -2,6 +2,11 @@
 [![Build Status](https://github.com/abookyun/einvoice/actions/workflows/build.yml/badge.svg)](https://github.com/abookyun/einvoice/actions/workflows/build.yml)
 [![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
 
 To support the thriving e-commerce industry and lower the business costs and barriers associated with printing paper receipts, the Taiwan Executive Yuan announced plans in August 2000 to implement electronic receipts in Taiwan and launched a comprehensive project in May 2010 to promote e-invoice applications. This initiative employs innovative approaches such as allowing consumers to claim virtual receipts via multiple devices, offering automatic checking of receipt lottery numbers, and providing a variety of channels for retailers to issue receipts.
@@ -67,7 +72,7 @@ Einvoice::Tradevan::Provider.new(ssl_verify: false)
 client = Einvoice::Client.new(Einvoice::Tradevan::Provider.new)
 ```
 
-### Issue an invoice
+### Issue an invoice (開立電子發票)
 
 ```ruby
 payload = {
@@ -138,7 +143,7 @@ result.data
 # }
 ```
 
-### Cancel an invoice
+### Cancel an invoice (作廢電子發票)
 
 ```ruby
 payload = {
@@ -165,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 = {
@@ -211,7 +283,7 @@ result.data
 # ]
 ```
 
-### Search invoice detail
+### Search invoice detail (發票開立明細查詢)
 
 ```ruby
 result = client.search_invoice_detail("GX38551078")
@@ -255,7 +327,7 @@ result.data
 # }
 ```
 
-### Send card info to customer
+### Send card info to customer (電子發票載具歸戶/中獎通知作業)
 
 ```ruby
 payload = {
@@ -275,7 +347,7 @@ result.successful?
 result.data
 ```
 
-### Get invoice mark info
+### Get invoice mark info (電子發票字軌號碼配額取號/分配作業)
 
 ```ruby
 payload = {
@@ -307,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/configuration.rb

@@ -20,7 +20,7 @@ module Einvoice
     DEFAULT_ENCRYPTION_KEYS = {}
     DEFAULT_SSL_VERIFY = true
 
-    attr_accessor *VALID_OPTIONS_KEYS
+    attr_accessor(*VALID_OPTIONS_KEYS)
 
     def self.extended(base)
       base.reset

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