nodexpay 0.1.0

data/docs/http-and-errors.md

@@ -0,0 +1,157 @@
+# HTTP とエラー
+
+## 既定 HTTP transport
+
+既定実装は Ruby 標準ライブラリの `Net::HTTP` を使用し、追加の runtime dependency を持ちません。
+
+- HTTPS の証明書検証を有効にする
+- request ごとに接続を作成し、可変な connection を Client 間で共有しない
+- `POST` だけを使用する
+- redirect を追従しない
+- transport / 503 の自動再試行を行わない
+- body は上位層で生成された form-urlencoded String をそのまま送る
+
+## Timeout
+
+既定値:
+
+| 設定 | 既定 | 対象 |
+| --- | --- | --- |
+| `open_timeout` | 5秒 | TCP/TLS 接続確立 |
+| `read_timeout` | 30秒 | response 読み取り |
+| `write_timeout` | 30秒 | request body 書き込み |
+
+client initializer で正の Numeric を指定できます。0、負数、NaN、Infinity は `ConfigurationError` とします。
+
+公式 FAQ の「API timeout はない」という記載は server 側上限の説明であり、client の無制限待機を意味するものとして扱いません。
+
+## Retry と結果不明状態
+
+Payment Request は、server が作成を完了した後に response を受け取れなかった場合があります。この状態で同じ `order_code` を再送すると、2021 duplicate が返り、元の payment token を回収できない可能性があります。
+
+そのため次を禁止します。
+
+- timeout、接続切断、503 に対する自動 retry
+- 新しい `order_code` を SDK が自動生成して retry
+- duplicate error を成功として扱うこと
+
+`TransportError` または `TimeoutError` を受けた利用側は、注文を「結果不明」として保持し、管理画面や別の業務手順で確認します。公式の照会 endpoint がないため、SDK は fallback を提供しません。
+
+## 例外階層
+
+```text
+NodexPay::Error
+├── ConfigurationError
+├── ValidationError
+├── SignatureVerificationError
+├── TransportError
+│   └── TimeoutError
+├── APIError
+│   ├── BadRequestError
+│   ├── ServiceUnavailableError
+│   └── UnexpectedHTTPStatusError
+└── InvalidResponseError
+```
+
+### ローカルエラー
+
+| 例外 | 条件 |
+| --- | --- |
+| `ConfigurationError` | credential、environment、timeout、transport 設定が不正 |
+| `ValidationError` | API 呼び出し引数が公開契約に違反 |
+| `SignatureVerificationError` | Payment Result の署名が一致しない |
+| `InvalidResponseError` | 成功 response または Payment Result の JSON/schema が不正 |
+
+### 通信エラー
+
+| 例外 | 条件 |
+| --- | --- |
+| `TimeoutError` | open/read/write timeout |
+| `TransportError` | DNS、TLS、connection reset、その他 response 未取得の通信障害 |
+
+`TimeoutError` は `TransportError` の subclass です。元例外は `cause` で参照可能にしますが、message に request body や credential を含めません。
+
+### API エラー
+
+`APIError` は次の読み取り専用属性を持ちます。
+
+```ruby
+error.operation        # :create_payment or :cancel_payment
+error.status           # Integer
+error.error_codes      # Array[Integer]
+error.response_headers # Hash[String, String]
+error.response_body    # String
+```
+
+`message` には operation、HTTP status、既知の error code 名だけを含めます。`identification_token`、`hash_token`、`verify_token`、request body は含めません。`response_body` は自動的に message や `inspect` へ展開せず、利用者にも機密情報として扱うよう文書化します。
+
+## HTTP status mapping
+
+| Status | 例外 |
+| --- | --- |
+| 200 | endpoint ごとの成功処理 |
+| 400 | `BadRequestError` |
+| 503 | `ServiceUnavailableError` |
+| その他 | `UnexpectedHTTPStatusError` |
+
+301/302/307/308 も `UnexpectedHTTPStatusError` です。別 host へ credential を転送しないため redirect は追従しません。
+
+## Error body の解析
+
+公式の400例は endpoint 間で形が異なり、一部は JSON として壊れています。SDK は成功扱いを広げる fallback ではなく、診断情報を失わないため次の限定的な抽出を行います。
+
+有効な JSON の場合、次の位置だけから error code を抽出します。
+
+```json
+{ "errors": [2021] }
+```
+
+```json
+{ "errors": 2024 }
+```
+
+```json
+{ "data": { "errors": [2021] } }
+```
+
+- scalar または Array の整数と、10進整数だけの String を Integer 化する
+- 上記以外の key を error code として走査しない
+- JSON が壊れている、または code を抽出できない場合は空配列にする
+- unknown code も数値のまま保持する
+- status と元 body は常に `APIError` に保持する
+
+503 の maintenance body は valid JSON schema が規定されていないため、status のみで `ServiceUnavailableError` にします。
+
+## 既知 error code
+
+少なくとも公開 endpoint と直接関係する次の code 名を定義します。
+
+| Code | Name |
+| --- | --- |
+| 2010 | `RECEIVED_IDENTIFICATION_TOKEN_EMPTY` |
+| 2011 | `RECEIVED_IDENTIFICATION_TOKEN_INVALID` |
+| 2020 | `RECEIVED_ORDER_CODE_EMPTY` |
+| 2021 | `RECEIVED_ORDER_CODE_DUPLICATE` |
+| 2022 | `RECEIVED_ORDER_CODE_ALREADY_CANCELLED` |
+| 2023 | `PAYMENT_NOT_FOUND` |
+| 2024 | `PAYMENT_NOT_CANCELABLE` |
+| 2030 | `RECEIVED_AMOUNT_INVALID_FORMAT` |
+| 2040 | `RECEIVED_INVALID_CALLBACK_URL` |
+| 2050 | `RECEIVED_COLOR_THEME_INVALID_FORMAT` |
+| 2060 | `RECEIVED_VERIFY_TOKEN_EMPTY` |
+| 2061 | `RECEIVED_VERIFY_TOKEN_INVALID` |
+| 2101 | `RECEIVED_EXT_RESERVED_INVALID` |
+| 2102 | `RECEIVED_EXT_DESCRIPTION_INVALID` |
+| 2370 | `RECEIVE_CONTRACT_UNPUBLISHED` |
+| 2460 | `RECEIVED_INVALID_DEADLINE` |
+
+公式 Payment Request ページには内部 API 用に見える多数の code も列挙されています。SDK は未知 code を破棄しないため、すべてを定数化しなくても診断可能です。
+
+## 秘密情報の取り扱い
+
+- Client の `inspect` は credential を表示しない
+- request body と signing string をログ出力しない
+- transport exception に URI path は含めても query/body は含めない
+- test fixture、recording、CI artifact に実 credential を保存しない
+- Hash Token は server-side でのみ使用し、browser/mobile bundle へ渡さない
+

data/docs/implementation-plan.md

@@ -0,0 +1,130 @@
+# 実装計画
+
+## リリース方針
+
+最初の公開版は `0.1.0` とします。Nodex Pay の正式 SDK を名乗らず、README と gem metadata に非公式 SDK であることを記載します。
+
+`1.0.0` は次を満たしてから公開します。
+
+- Testnet で Payment Request → Payment Cancel の contract を確認済み
+- 実運用相当の endpoint で Payment Result payload と署名を確認済み
+- 公式文書の未確認事項が、解決済みまたは明示された制限として整理済み
+- Ruby 3.4 / 4.0 の CI、RBS、package 検査が安定している
+
+公開ライセンスは MIT とします。公開 API の修正時に旧 keyword、alias、domain fallback を安易に追加しません。1.0 以降の破壊的変更は SemVer の major version で表現します。
+
+## Phase 1: Gem scaffold
+
+### 変更
+
+- gem 名 `nodexpay`、require path `nodex_pay`、namespace `NodexPay` で scaffold を作る
+- `required_ruby_version` を `>= 3.4` にする
+- runtime dependency を追加しない
+- Minitest、RBS、Sorbet RBI、CI、package build の最小構成を追加する
+- Sorbet RBI は型エラーなしとmetrics上のsignature/strict-file coverage 100%をCIで必須にする
+- MIT license、非公式 SDK の表示、version `0.1.0` を追加する
+
+### 完了条件
+
+- `require "nodex_pay"` が成功する
+- Ruby 3.4 / 4.0 で空の test suite と RBS 検査が成功する
+- build した gem に意図した lib、sig、docs、license だけが含まれる
+
+## Phase 2: Value、validation、署名
+
+### 変更
+
+- immutable な設定、`Payment`、`PaymentResult`、transport value を `Data` で定義する
+- `order_code`、enum、description、deadline、timeout の validator を実装する
+- String / Integer / BigDecimal を単一の decimal serializer へ集約する
+- SHA-256 signer と constant-time verifier を pure object/function として実装する
+- [testing.md](testing.md) の固定署名ベクトルを追加する
+
+### 完了条件
+
+- 署名と form field が同じ normalized amount を使うことを unit test で証明する
+- Float、指数表記、範囲外を送信前に拒否する
+- 秘密情報が各 object の `inspect` に含まれない
+
+## Phase 3: HTTP transport と例外
+
+### 変更
+
+- `Request` / `Response` contract と `Net::HTTP` transport を実装する
+- TLS、open/read/write timeout、header、form body を設定する
+- 例外階層、HTTP status mapping、限定的な error code decoder を実装する
+- redirect と retry を実装しないことを test で固定する
+
+### 完了条件
+
+- local server integration test で exact method/header/body を確認する
+- timeout / DNS / TLS / connection failure が契約どおりの例外になる
+- 400 の既知形状、503、unknown status、malformed body で診断情報を保持する
+
+## Phase 4: Payment Request と Cancel
+
+### 変更
+
+- 環境から固定 base URL を選択する
+- `create_payment` を実装し、form request と `Payment` decoder を接続する
+- `cancel_payment` を amount なしの署名で実装する
+- 成功 response と不正 response の endpoint-specific test を追加する
+
+### 完了条件
+
+- [api-contract.md](api-contract.md) の全 keyword と wire field が一致する
+- `ext_reserved` / `callback_url` を送信できる非公開経路が存在しない
+- Cancel の200だけが `true` を返し、2022を含む400は例外になる
+
+## Phase 5: Payment Result
+
+### 変更
+
+- raw JSON parser と field/type validator を実装する
+- 受信した amount を変更せず署名検証する
+- 検証成功後にのみ `PaymentResult` を構築する
+- 署名対象外 field とリプレイ制約を利用ガイドへ記載する
+
+### 完了条件
+
+- 正常/不正署名、欠落/型違い、`result: false` の全 test が成功する
+- 未検証 payload がモデルや例外から外部へ漏れない
+- Rails/Rack、DB、ACK response の責務が SDK 内へ混入していない
+
+## Phase 6: RBS/Sorbet RBI、文書、Testnet
+
+### 変更
+
+- 公開 API、モデル、transport、例外を RBS へ反映する
+- RBS と同じ公開契約を `rbi/nodex_pay.rbi` へ反映し、gem に同梱する
+- root README にインストール、設定、3 API の最小例、非公式表示を追加する
+- この設計文書と実装の名称・引数・戻り値を照合する
+- 資格情報を必要とする手動 Testnet smoke job を追加する
+
+### 完了条件
+
+- Ruby 3.4 / 4.0 の CI が成功する
+- RBS/Sorbet RBI と Ruby の公開 API が一致する
+- Testnet で create → cancel を実行し、Content-Type、Cancel 署名、成功 body を確認する
+- 観測結果が設計と異なる場合は、実装の fallback ではなく設計判断を更新する
+
+## 0.1.0 Definition of Done
+
+- `gem install nodexpay` と `require "nodex_pay"` が成立する
+- 3つの公開メソッド以外に推測 API を公開していない
+- outbound request は form-urlencoded、retry/redirect は無効である
+- 全 credential と署名材料がログ、例外 message、test artifact から除外されている
+- API/model/error/transport の RBS と Sorbet RBI が同梱されている
+- docs、tests、実装が同じ契約を参照している
+- MIT license と非公式 SDK 表示が配布物に含まれる
+
+## 1.0 前に Nodex 側へ確認する項目
+
+1. outbound request の正式な Content-Type
+2. amount の server-side lexical normalization
+3. Cancel の署名原文と success response
+4. `ext_reserved` の現行 request field としての可否
+5. Payment Result の必須 field、failure payload、ACK、retry
+6. rate limit、API timeout、secret rotation、deprecation policy
+
+回答が得られない項目は、Testnet/実環境で観測できた範囲と未保証範囲を明記します。観測できない機能を推測して実装しません。

data/docs/payment-results.md

@@ -0,0 +1,109 @@
+# Payment Result
+
+Payment Result API は、Nodex Pay が blockchain 上の支払い結果を確認した後、加盟店が管理画面で指定した URL へ送る JSON POST です。SDK は Web サーバーを提供せず、raw request body の解析と署名検証だけを担当します。
+
+## 公開 API
+
+```ruby
+result = client.verify_payment_result(raw_request_body)
+```
+
+成功時は `NodexPay::PaymentResult`、JSON/field が不正な場合は `InvalidResponseError`、署名不一致の場合は `SignatureVerificationError` を返します。
+
+署名不一致を Boolean で返す低水準 API は公開しません。未検証データを業務処理へ渡さないためです。
+
+## 受信形式
+
+Content-Type は公式仕様どおり `application/json` です。利用側は HTTP body を文字コード変換、parameter merge、symbolize する前に String として SDK へ渡します。
+
+```json
+{
+  "order_code": "order-123",
+  "transaction_code": "A1B2-3CD4-5E6F",
+  "amount": "100",
+  "symbol": "USDT",
+  "result": true,
+  "verify_token": "lowercase-sha256-hex",
+  "chain_id": "1",
+  "transaction_hash": "0x..."
+}
+```
+
+公式ページに完全な payload 例はないため、上記は field の組み合わせを示す SDK 文書上の例です。
+
+## field contract
+
+| Field | 型 | SDK の検査 |
+| --- | --- | --- |
+| `order_code` | String | 空でないこと |
+| `transaction_code` | String | `\A[A-Za-z0-9]{4}(?:-[A-Za-z0-9]{4}){2}\z` に一致する14 characters |
+| `amount` | String | 空でないこと。署名用にそのまま保持 |
+| `symbol` | String | 空でないこと。固定 enum にはしない |
+| `result` | Boolean | `true` または `false` だけを許可 |
+| `verify_token` | String | 64 characters の16進 SHA-256 |
+| `chain_id` | String | 空でないこと。固定 enum にはしない |
+| `transaction_hash` | String | 空でないこと |
+
+すべての field を必須として扱います。公式 table に required marker はありませんが、各 field の省略時動作も定義されていないため、欠落を許容して不完全なモデルを生成することはしません。
+
+`symbol` と `chain_id` は、対応 token/network の追加を妨げないよう SDK の enum validation を行いません。
+
+## 署名検証
+
+受信した文字列を次の順番で連結し、client の `hash_token` を使って SHA-256 を計算します。
+
+```text
+<order_code>::<amount>::<hash_token>
+```
+
+重要な点:
+
+- `amount` は数値化、丸め、末尾ゼロ削除を行わない
+- 受信した `verify_token` は小文字へ変換せず、正規の64桁小文字 hex として検査する
+- 長さを検査した後、`OpenSSL.fixed_length_secure_compare` 相当の constant-time comparison を行う
+- `hash_token` や生成した raw signing string を例外、ログ、inspect へ含めない
+
+## 署名のセキュリティ境界
+
+> [!WARNING]
+> 公式署名が保護するのは `order_code` と `amount` だけです。`result`、`transaction_code`、`symbol`、`chain_id`、`transaction_hash` は署名対象ではありません。署名検証の成功だけで payload 全体の完全性や blockchain finality が保証されたと扱ってはいけません。
+
+利用アプリケーションは、検証後に少なくとも次を行います。
+
+1. `order_code` に対応する注文が存在することを確認する。
+2. 保存済みの注文金額・受取 token と `amount` / `symbol` を照合する。
+3. `transaction_code` を一意 key として、同じ通知を重複処理しない。
+4. 既に確定した注文を古い通知や矛盾する通知で上書きしない。
+5. 高い finality が必要な場合は、`transaction_hash` を explorer / JSON-RPC で別途確認する。
+
+これらは加盟店のデータストアと業務規則を必要とするため SDK の責務には含めません。
+
+## HTTP endpoint 側の責務
+
+SDK は Rack/Rails response を生成しません。利用側 endpoint は次を担当します。
+
+- `Content-Type` と request size を確認する
+- raw body を一度だけ読み取って `verify_payment_result` へ渡す
+- 検証成功後、トランザクション内で重複排除と状態更新を行う
+- 保存成功後にのみ 2xx を返す
+- 例外時の response、監視、再処理方針を決める
+
+公式文書は ACK body、必要な status、timeout、再送回数、再送間隔、順序保証を規定していません。SDK は特定の ACK や retry protocol を仮定しません。
+
+## リプレイと重複
+
+Payment Result には timestamp、nonce、delivery ID がありません。署名検証だけでは同一 payload の再送を検出できません。
+
+`transaction_code` を一意制約付きで保存し、同じ値の再受信は同じ結果を返す業務処理を推奨します。ただし、この一意性管理は SDK がメモリ内で代替してはいけません。複数プロセス・再起動をまたぐ永続性が必要だからです。
+
+## Finality
+
+公式 FAQ には blockchain reorganization を完全には考慮しない旨の記載があります。`result: true` は Nodex Pay が成功として通知した事実を表しますが、不可逆な blockchain finality の保証ではありません。
+
+## Nodex 側への確認事項
+
+1. 必須 field と failure notification 時の nullability
+2. ACK に必要な HTTP status / body
+3. timeout、再送、重複、順序の保証
+4. source IP、追加認証、secret rotation の仕様
+5. `result` と transaction field を含む署名方式への拡張予定

data/docs/testing.md

@@ -0,0 +1,175 @@
+# テスト戦略
+
+テストは、外部 API を推測した柔軟な挙動ではなく、この設計文書で固定した公開契約を検証します。unit test は Minitest、型検査は RBS と Sorbet を使用します。
+
+## テスト階層
+
+| 階層 | 目的 | 外部通信 |
+| --- | --- | --- |
+| Unit | validation、金額正規化、署名、decoder、モデル | なし |
+| Client contract | Client から transport へ渡る request と戻り値/例外 | fake transport |
+| Net::HTTP integration | form body、header、timeout、TLS/connection error mapping | local test server |
+| Testnet smoke | Nodex Pay の実際の wire contract | 手動・資格情報必須 |
+
+Production API は自動テストや CI から呼び出しません。
+
+## 固定署名ベクトル
+
+署名テストは最低限、次を固定 fixture として使用します。
+
+### 金額あり
+
+```text
+raw:
+ORDER-123::10::hash-secret
+
+sha256:
+b9087ce2f0af360db0a0172df536f755e25700b13601306831224ae69d22631a
+```
+
+### 金額なし
+
+```text
+raw:
+ORDER-123::::hash-secret
+
+sha256:
+3816f1a2297c926880d0859439a7da193959936d4816dd28000e18428599c0a3
+```
+
+`10` と `10.0` は異なる digest になるため、Client contract test では正規化後の文字列が署名入力と form field の両方で同一であることを直接検証します。
+
+## Configuration
+
+- `:production` と `:testnet` を受け付ける
+- environment 未指定、未知 Symbol/String を拒否する
+- 空の `identification_token` / `hash_token` を拒否する
+- timeout の既定値が 5/30/30 秒である
+- 正の Integer/Float timeout を受け付け、0、負数、NaN、Infinity を拒否する
+- custom transport が `call` contract を満たさない場合を明確な `ConfigurationError` にする
+- Client の `inspect` に credential が含まれない
+
+## 金額と入力 validation
+
+### 正常系
+
+- String、Integer、BigDecimal を受け付ける
+- `"10.00"`、`10`、`BigDecimal("10.0")` を `"10"` にする
+- `"10.50"` を `"10.5"` にする
+- 最小値 `0.000001` と最大値 `100000000` を受け付ける
+- amount nil 時に form から `amount` を完全に省略する
+- Time deadline を Unix time 秒へ変換する
+- enum の Symbol/String と大文字・小文字を規定どおり正規化する
+
+### 異常系
+
+- Float、指数表記、先頭ゼロ、負数、ゼロ、範囲外、空文字列を拒否する
+- NaN、Infinity を拒否する
+- 非 ASCII、空、256 bytes 以上の `order_code` を拒否する
+- 未知の `amount_type`、`color_theme`、`ui_mode` を拒否する
+- 101 characters 以上または不正 UTF-8 の description 系 field を拒否する
+- 負の deadline、Time/Integer 以外の deadline を拒否する
+
+## Payment Request
+
+- environment ごとに正しい `/payment/receive` URI を組み立てる
+- method、Accept、Content-Type、User-Agent が契約どおりである
+- form body に credential、order code、digest、全 optional field が正しい wire name で入る
+- `ui_mode` が `uimode` になる
+- nil の optional field、`ext_reserved`、`callback_url`、`hash_token` が body に入らない
+- 200 JSON を `Payment` へ変換する
+- `ext_reserved` / `ext_description` の欠落と null を nil として扱う
+- `url` / `token` 欠落、型違い、invalid JSON を `InvalidResponseError` にする
+
+## Payment Cancel
+
+- environment ごとに正しい `/payment/cancel` URI を組み立てる
+- 署名が必ず `order_code::::hash_token` である
+- body に `amount` が入らない
+- 200 の空 body、`{}`、その他の body で一律 `true` を返す
+- 2022、2023、2024 を含む400を `BadRequestError` にする
+- 2022 を成功へ読み替えない
+
+## HTTP と API error
+
+- top-level `errors` の Array/scalar を抽出する
+- `data.errors` の Array/scalar を抽出する
+- 数値 String は code 化し、非数値値は無視する
+- unknown code を保持する
+- malformed JSON と plain text body でも status/body を失わない
+- 400、503、未知 status、redirect status を正しい例外へ変換する
+- open/read/write timeout を `TimeoutError` にする
+- DNS、TLS、connection reset を `TransportError` にする
+- どの通信エラーにも自動 retry しない
+- redirect の Location へ2回目の request を送らない
+- 例外の message / inspect に credential、verify token、request body が含まれない
+
+## Payment Result
+
+### 正常系
+
+- 正しい JSON と署名を `PaymentResult` へ変換する
+- `amount` の末尾ゼロを変更せず署名に使い、モデルにも保持する
+- `result: true` と `result: false` を受け付ける
+- `success?` が `result` と一致する
+- 未知の `symbol` / `chain_id` を String として保持する
+
+### 異常系
+
+- invalid JSON、配列 top-level、欠落 field、null、型違いを拒否する
+- transaction code の形式違反を拒否する
+- verify token の長さ、文字種、大文字 hex を拒否する
+- order code、amount、hash token のいずれかが異なる署名を拒否する
+- `result` や transaction field の変更だけでは公式署名が変化しないという制約を、期待されるセキュリティ境界として明示的にテストする
+- 署名不一致時に未検証の payload/model を例外へ含めない
+
+## Transport contract
+
+fake/custom transport 共通の contract test を用意します。
+
+- `call(Request)` を1回だけ呼ぶ
+- `Response` の status が Integer、headers が Hash、body が String であることを要求する
+- response 型違反を `InvalidResponseError` にする
+- transport が body を変更しないことを、local server が受け取った exact body で確認する
+
+## CI matrix
+
+| 対象 | 内容 |
+| --- | --- |
+| Ruby | 3.4、4.0 の最新 patch |
+| Tests | 全 Minitest |
+| Types | RBS validation、同梱 RBI の `srb tc`、Sorbet signature/strict-file coverage 100%検査 |
+| Package | `gem build` と gem contents 検査 |
+| Docs | Markdown link、相対リンク、コードブロック、表の検査 |
+
+CI は credential を要求せず、Testnet smoke test とは分離します。
+
+## Testnet smoke test
+
+資格情報を環境変数から受け取る手動ジョブとして実行します。
+
+1. timestamp と random suffix を含む一意な `order_code` を生成する。
+2. 最小限の固定額で Payment Request を1回実行する。
+3. `url` と `token` の型を確認する。値そのものはログへ出さない。
+4. 同じ `order_code` を Payment Cancel へ渡す。
+5. HTTP status、Content-Type、response schema の観測結果を秘密情報なしで記録する。
+
+通信結果が不明な場合に自動で再実行しません。失敗時の order code は、管理画面で確認できるよう秘密でない artifact として保持します。
+
+Payment Result の実環境確認は、専用の加盟店 endpoint と testnet payment が必要なため別の手動受入試験とします。
+
+## 完了条件
+
+- Ruby 3.4 / 4.0 の全テストが成功する
+- 固定ベクトルと exact form body test が成功する
+- すべての例外 path で秘密情報が露出しない
+- Production への自動通信が存在しない
+- このディレクトリの公開 API、引数、モデル、例外名が実装・RBS・Sorbet RBI・テストと一致する
+- Sorbet RBI に型エラーがなく、metrics上のsignature coverageとstrict-file coverageがともに100%である
+
+Sorbetのcoverageは、同梱RBIについて次のように定義します。
+
+- signature coverage: `types.sig.count / types.input.foundmethods.total`
+- strict-file coverage: `types.input.files.sigil.strict / rbi/**/*.rbi のファイル数`
+
+`script/check_sorbet.rb` が両方を計算し、100%未満なら終了statusを非0にします。SorbetではRubyの `Data.define` が生成するinitializerとRBIのkeyword initializerを重ねると誤った再定義判定が起きるため、この検査は配布物であるRBIを単独で実行します。

data/lib/nodex_pay/amount_serializer.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module NodexPay
+  module AmountSerializer
+    MINIMUM = "0.000001"
+    MAXIMUM = "100000000"
+    DECIMAL_PATTERN = /\A(?:0|[1-9][0-9]*)(?:\.[0-9]+)?\z/
+
+    module_function
+
+    def serialize(amount)
+      raw = case amount
+            when String
+              validate_string!(amount)
+              amount
+            when Integer
+              amount.to_s
+            else
+              bigdecimal_value(amount)
+            end
+
+      normalized = normalize(raw)
+      validate_string!(normalized)
+      unless compare_decimals(normalized, MINIMUM) >= 0 && compare_decimals(normalized, MAXIMUM) <= 0
+        raise ValidationError, "amount must be between 0.000001 and 100000000"
+      end
+
+      normalized
+    rescue ArgumentError
+      raise ValidationError, "amount must be a plain decimal value"
+    end
+
+    def validate_string!(amount)
+      return if DECIMAL_PATTERN.match?(amount)
+
+      raise ValidationError, "amount must use plain decimal notation without leading zeroes"
+    end
+    private_class_method :validate_string!
+
+    def normalize(value)
+      integer, fraction = value.split(".", 2)
+      return integer unless fraction
+
+      fraction = fraction.sub(/0+\z/, "")
+      fraction.empty? ? integer : "#{integer}.#{fraction}"
+    end
+    private_class_method :normalize
+
+    def bigdecimal_value(amount)
+      unless defined?(::BigDecimal) && amount.is_a?(::BigDecimal)
+        raise ValidationError, "amount must be a String, Integer, or BigDecimal"
+      end
+      unless amount.finite?
+        raise ValidationError, "amount must be between 0.000001 and 100000000"
+      end
+
+      amount.to_s("F")
+    end
+    private_class_method :bigdecimal_value
+
+    def compare_decimals(left, right)
+      left_integer, left_fraction = left.split(".", 2)
+      right_integer, right_fraction = right.split(".", 2)
+      left_fraction ||= ""
+      right_fraction ||= ""
+
+      integer_comparison = left_integer.length <=> right_integer.length
+      return integer_comparison unless integer_comparison.zero?
+
+      integer_comparison = left_integer <=> right_integer
+      return integer_comparison unless integer_comparison.zero?
+
+      width = [left_fraction.length, right_fraction.length].max
+      left_fraction.ljust(width, "0") <=> right_fraction.ljust(width, "0")
+    end
+    private_class_method :compare_decimals
+  end
+end