paid_tw-ubn 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1235c21850cf6463a28a5ffaebf881de7c52e76019319883414ca2d0b694a0b8
+  data.tar.gz: d1c2e35153e2cbfb248e616290f28b1142d4d8719fb8c66e6345e9dc44b34409
+SHA512:
+  metadata.gz: 3bb51f144ba623cb7d548a88a81d7b323b1deeae215f40ec16d565b1dfabe09c3b02262d8cd261005a9984012f7381625fd378db9b1053a2ba363efd1c6518ce
+  data.tar.gz: f0db2095e1a65c3b9fb62d4d233dd514ae31b4aee1a25433a3ae0b99ec874a260ae56af410a7c05c927803b176bbec993bf892c4f0f8d1d2308acf58094bb56d

data/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2026 paid.tw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTE: This MIT license covers the SOURCE CODE in this repository only.
+
+The published DATA artifacts are derived from open data released by
+財政部財政資訊中心 under 政府資料開放授權條款－第1版 (Open Government Data
+License v1, https://data.gov.tw/license). Failing to attach the 顯名聲明
+below means the licence was not granted.
+
+提供機關／單位：財政部財政資訊中心
+開放資料：
+  - 全國營業(稅籍)登記資料集（https://data.gov.tw/dataset/9400，BGMOPEN1.zip）
+  - 全國營業(稅籍)登記(停業)資料集（https://data.gov.tw/dataset/75140，BGMOPEN1X.csv）
+版本：each build's extract date, recorded in manifest.json as dataDate and
+attribution.datasets[].version (for example 28-OCT-26).
+
+此開放資料依政府資料開放授權條款 (Open Government Data License) 進行公眾釋出，使用者於遵守本條款各項規定之前提下，得利用之。
+
+政府資料開放授權條款：https://data.gov.tw/license
+
+See docs/data-dictionary.md. Per-record GCIS responses, when used, are a
+separate government source under the same licence and need their own
+attribution; this repository does not republish a GCIS dump.

data/README.md

@@ -0,0 +1,62 @@
+# paid_tw-ubn
+
+The Ruby counterpart of the [`@paid-tw/ubn`](https://www.npmjs.com/package/@paid-tw/ubn)
+npm client, for the server side of a checkout: validate a Taiwan Unified
+Business Number (統一編號), compare an invoice title (抬頭) with the registered
+name, and look the registered name up through a deployed
+[tw-ubn](https://github.com/paid-tw/tw-ubn) Worker.
+
+Pure Ruby, no runtime dependencies, Ruby 3.2 or later.
+
+```ruby
+# Gemfile
+gem 'paid_tw-ubn'
+```
+
+```ruby
+require 'paid_tw/ubn'
+
+PaidTw::Ubn.valid?('22099131')   # => true (post-2023 rule: sum divisible by 5)
+
+title = PaidTw::Ubn.lookup_title('22099131', base_url: 'https://ubn.example.com', timeout: 2)
+
+if title.nil?
+  # No answer: bad checksum, timeout, network error, non-2xx, or a name that
+  # cannot be used as a title. Treat the UBN as not looked up.
+elsif !title.found?
+  # No public source has this UBN. Not proof that it is invalid.
+else
+  title.name                      # => "台灣積體電路製造股份有限公司"
+  title.status                    # => "active", "suspended", "closed" or nil (unknown)
+  PaidTw::Ubn.same_title?(typed_title, title.name)
+end
+```
+
+| Ruby | npm client |
+|---|---|
+| `PaidTw::Ubn.valid?(ban)` | `validateUBN(ban)` |
+| `PaidTw::Ubn.lookup_title(ban, base_url:, timeout:)` | `lookupTitle(ban, { baseUrl, timeoutMs })` |
+| `PaidTw::Ubn.same_title?(a, b)` | `isSameTitle(a, b)` |
+| `PaidTw::Ubn.private_use?(title)` | `hasPrivateUse(title)` |
+
+`lookup_title` never raises. `timeout` is in seconds and bounds the connection
+and each read, not the whole call; the request is not retried. A found `Title`
+also carries `ban`, `address`, `use_invoice`, `kind`, `source`,
+`company_status`, `closed_date` and `setup_date`, each nil when the Worker did
+not send it. What a lookup result means, and why "not found" is not "invalid",
+is in the [repository README](https://github.com/paid-tw/tw-ubn#readme).
+
+`same_title?` ignores full- vs half-width forms (NFKC), 臺 vs 台, whitespace and
+Latin case. It never strips or abbreviates a legal form such as 股份有限公司.
+
+The shard reader (`lookupVAT`, `shardOf`) and the direct FIA / GCIS clients of
+the npm package are not ported: a server should ask the Worker, which caches.
+
+## Develop
+
+```bash
+cd ruby && bundle install && bundle exec rake test
+```
+
+The tests read the vectors in [`../fixtures`](../fixtures), which the npm
+client's tests read too, and the Rust core's sample of real UBNs.

data/lib/paid_tw/ubn/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PaidTw
+  module Ubn
+    VERSION = '0.1.0'
+  end
+end

data/lib/paid_tw/ubn.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'ubn/version'
+
+module PaidTw
+  # Taiwan Unified Business Number (UBN/BAN) helpers: checksum
+  # validation, invoice-title comparison, and a title lookup against a deployed
+  # tw-ubn Worker. The Ruby counterpart of the `@paid-tw/ubn` npm client; the
+  # two are held together by the vectors in `fixtures/`.
+  module Ubn
+    WEIGHTS = [1, 2, 1, 2, 1, 2, 4, 1].freeze
+
+    # What ECMAScript's `\s` matches, so that a title compares the same here as
+    # in the npm client. Ruby's own `\s` is ASCII-only and `[[:space:]]` differs
+    # on U+0085 and U+FEFF.
+    WHITESPACE = "\t\n\v\f\r    - 

  　"
+    WHITESPACE_RUN = /[#{WHITESPACE}]+/
+    PRIVATE_USE = /\p{Co}/
+
+    # A capital sigma that ends a word: a cased letter before it and none after
+    # it, case-ignorable characters (combining marks, full stops, apostrophes,
+    # ...) skipped on both sides. ECMAScript's `toLowerCase` gives it the final
+    # form "ς"; Ruby's `downcase` knows no context and gives "σ". A character
+    # that is both cased and case-ignorable counts as ignorable, as JavaScript
+    # engines have it.
+    CASED = '[\p{Cased}&&\P{Case_Ignorable}]'
+    FINAL_SIGMA = /(#{CASED}\p{Case_Ignorable}*)Σ(?!\p{Case_Ignorable}*#{CASED})/
+
+    STATUSES = %w[active suspended closed].freeze
+    KINDS = %w[business nonprofit school agency].freeze
+    SOURCES = %w[dataset fia-api gcis].freeze
+
+    DEFAULT_TIMEOUT = 2
+    SUCCESS = (200..299)
+
+    # The answer of `lookup_title`. `found?` is false when the Worker answered
+    # and no source it consulted has a record; every other field is then nil.
+    # A nil `status` means unknown, not active.
+    Title = Data.define(
+      :found, :ban, :name, :status, :address, :use_invoice, :kind, :source,
+      :company_status, :closed_date, :setup_date
+    ) do
+      def initialize(found:, ban: nil, name: nil, status: nil, address: nil, use_invoice: nil,
+                     kind: nil, source: nil, company_status: nil, closed_date: nil, setup_date: nil)
+        super
+      end
+
+      def found? = found
+    end
+
+    NOT_FOUND = Title.new(found: false)
+
+    module_function
+
+    # True when `ban` is a well-formed 8-digit UBN under the post-2023 rule
+    # (weighted digit sum divisible by 5). It says nothing about whether the
+    # number is registered. Never raises: a value that is not a string, or a
+    # string whose bytes are invalid in its own encoding, is false.
+    def valid?(ban)
+      # A regexp raises on a string it cannot read: one with invalid bytes, or
+      # in an encoding that is not ASCII-compatible (UTF-16, UTF-32).
+      return false unless ban.is_a?(String) && ban.encoding.ascii_compatible? && ban.valid_encoding?
+      return false unless ban.match?(/\A[0-9]{8}\z/)
+
+      sum = ban.each_char.with_index.sum do |char, index|
+        product = char.to_i * WEIGHTS[index]
+        (product / 10) + (product % 10)
+      end
+
+      (sum % 5).zero? || (ban[6] == '7' && ((sum + 1) % 5).zero?)
+    end
+
+    # True when `title` contains a Unicode Private Use Area character. The tax
+    # registry writes some names with locally-defined glyphs mapped there; they
+    # render as boxes and an e-invoice platform rejects them.
+    def private_use?(title)
+      utf8(title).match?(PRIVATE_USE)
+    end
+
+    # True when two invoice titles name the same entity once incidental typing
+    # differences are ignored: full- vs half-width forms (NFKC), the two
+    # spellings of "tai" (U+81FA and U+53F0), all whitespace, and Latin case.
+    # Legal forms are never stripped or abbreviated ("Co., Ltd." written in
+    # full is not its bracketed short form), and an empty title matches nothing.
+    # Neither does a title with bytes that have no reading as UTF-8: a string
+    # in another encoding is compared by its characters, one that is broken or
+    # binary with non-ASCII bytes is not compared at all.
+    def same_title?(a, b)
+      normalized = normalize_title(a)
+      !normalized.empty? && normalized == normalize_title(b)
+    end
+
+    # Looks up the registered name of `ban` through a deployed tw-ubn Worker
+    # (`GET <base_url>/v1/vat/<ban>`). Never raises. Three outcomes:
+    #
+    # - a `Title` with `found?` true: a registration with a usable name. Its
+    #   `status` may be "suspended" or "closed"; what to do then is the
+    #   caller's call.
+    # - `NOT_FOUND`: the Worker answered and no source has a record. This is
+    #   not proof of an invalid UBN: many withholding-unit UBNs (clinics,
+    #   professional practices, ...) have no public record.
+    # - nil: no answer. A malformed UBN (no request is made), a timeout, a
+    #   network error, any non-2xx response, a body that is not the expected
+    #   JSON, a `ban` in the body other than the one asked for, or a name that
+    #   is empty or carries Private Use Area glyphs.
+    #
+    # `timeout` is in seconds and bounds the connection and each read, not the
+    # whole call. `http` replaces the transport: a callable taking the URL and
+    # the timeout, returning `[status, body]`.
+    def lookup_title(ban, base_url:, timeout: DEFAULT_TIMEOUT, http: nil)
+      return nil unless valid?(ban)
+
+      url = "#{base_url.to_s.sub(%r{/+\z}, '')}/v1/vat/#{ban}"
+      status, body = (http || method(:get)).call(url, timeout)
+      return nil unless SUCCESS.cover?(status)
+
+      parse(JSON.parse(body), ban)
+    rescue StandardError
+      nil
+    end
+
+    def get(url, timeout)
+      uri = URI.parse(url)
+      raise ArgumentError, "not an http(s) URL: #{url}" unless uri.is_a?(URI::HTTP)
+
+      options = {
+        use_ssl: uri.scheme == 'https',
+        open_timeout: timeout,
+        read_timeout: timeout,
+        write_timeout: timeout,
+        # Net::HTTP retries an idempotent request once, which would double the
+        # time a dead Worker can hold the caller.
+        max_retries: 0
+      }
+      Net::HTTP.start(uri.host, uri.port, **options) do |connection|
+        connection.request_get(uri.request_uri) do |response|
+          status = response.code.to_i
+          # The status is all a non-2xx response has to say. Returning from
+          # inside the block leaves before Net::HTTP reads the body, and closes
+          # the connection: an error body that stalls or trickles holds no one.
+          return [status, nil] unless SUCCESS.cover?(status)
+
+          return [status, response.read_body]
+        end
+      end
+    end
+
+    def parse(body, ban)
+      return nil unless body.is_a?(Hash)
+
+      found = body['found']
+      return nil unless [true, false].include?(found)
+      return nil if body.key?('ban') && body['ban'] != ban
+      return NOT_FOUND unless found
+
+      name = body['name']
+      return nil unless name.is_a?(String) && !name.gsub(WHITESPACE_RUN, '').empty?
+      return nil if body['nameHasPrivateUse'] == true || private_use?(name)
+
+      Title.new(
+        found: true,
+        ban: ban,
+        name: name,
+        status: one_of(body['status'], STATUSES),
+        address: string(body['address']),
+        use_invoice: [true, false].include?(body['useInvoice']) ? body['useInvoice'] : nil,
+        kind: one_of(body['kind'], KINDS),
+        source: one_of(body['source'], SOURCES),
+        company_status: string(body['companyStatus']),
+        closed_date: string(body['closedDate']),
+        setup_date: string(body['setupDate'])
+      )
+    end
+
+    # A title that has no reading as UTF-8 normalizes to the empty title, which
+    # matches nothing. Replacing its unreadable bytes instead would turn each
+    # into the same U+FFFD and make different titles compare equal.
+    def normalize_title(title)
+      text = title.to_s.encode(Encoding::UTF_8)
+      return '' unless text.valid_encoding?
+
+      text
+        .unicode_normalize(:nfkc)
+        .tr('臺', '台')
+        .gsub(WHITESPACE_RUN, '')
+        .then { |stripped| lowercase(stripped) }
+    rescue EncodingError
+      ''
+    end
+
+    # `String#downcase` as ECMAScript's `toLowerCase` has it: see FINAL_SIGMA.
+    def lowercase(text)
+      return text.downcase unless text.include?('Σ')
+
+      text.gsub(FINAL_SIGMA, '\1ς').downcase
+    end
+
+    def utf8(value)
+      value.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    end
+
+    def one_of(value, allowed)
+      value if allowed.include?(value)
+    end
+
+    def string(value)
+      value if value.is_a?(String)
+    end
+
+    private_class_method :get, :parse, :normalize_title, :lowercase, :utf8, :one_of, :string
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: paid_tw-ubn
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- paid-tw
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'The Ruby counterpart of the @paid-tw/ubn npm client: validate a Taiwan
+  Unified Business Number, compare an invoice title with the registered name, and
+  look the registered name up through a deployed tw-ubn Worker.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/paid_tw/ubn.rb
+- lib/paid_tw/ubn/version.rb
+homepage: https://github.com/paid-tw/tw-ubn
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/paid-tw/tw-ubn/tree/main/ruby
+  changelog_uri: https://github.com/paid-tw/tw-ubn/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/paid-tw/tw-ubn/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Taiwan business number (統一編號) checksum, invoice-title comparison and title
+  lookup
+test_files: []