nodexpay 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0fb30ad3f3fb5a354c9999d7fb6646ddc2e774bc69a5e015d63ffbe77b45e3a3
+  data.tar.gz: d0c36c2d71fd2380125befefc0750cc2109b5994c443e325992233743cb09956
+SHA512:
+  metadata.gz: 236d4779b29f5552ce0c091c8f69e8944b6ca7bca4d0664e581d41954171f3a17785a503f9860d8bf43e2253f2d8c86bc4ce64ba1874a73da595a32e0a19d682
+  data.tar.gz: a62cb00c75beb8b19367e0afc077f4f79b9e6a4fcdb7baaf60e20d9bc7af83163b130d134bd24c14e8af303f24ceb891f72d761024f02076a8379a130b0e90ff

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 supermomonga
+
+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.
+

data/README.md

@@ -0,0 +1,125 @@
+# nodexpay
+
+Nodex Pay API の非公式 Ruby クライアント SDK です。支払いの作成・取消と、Payment Result callback の署名検証を提供します。Ruby 3.4 以上に対応し、runtime dependency はありません。
+
+> [!IMPORTANT]
+> この gem は Nodex Pay または Nodex Global Limited が提供・承認する公式 SDK ではありません。実運用前に [Nodex Pay API ドキュメント](https://nodex-pay.gitbook.io/docs/integration-guide/apis) と Testnet で挙動を確認してください。
+
+## インストール
+
+Gemfile に追加します。
+
+```ruby
+gem "nodexpay"
+```
+
+または直接インストールします。
+
+```shell
+gem install nodexpay
+```
+
+## クライアント
+
+Production と Testnet の取り違えを防ぐため、`environment` に既定値はありません。
+
+```ruby
+require "nodex_pay"
+
+client = NodexPay::Client.new(
+  identification_token: ENV.fetch("NODEX_PAY_IDENTIFICATION_TOKEN"),
+  hash_token: ENV.fetch("NODEX_PAY_HASH_TOKEN"),
+  environment: :testnet
+)
+```
+
+必要に応じて `open_timeout`、`read_timeout`、`write_timeout` を秒単位で指定できます。既定値はそれぞれ5秒、30秒、30秒です。
+
+## 支払いを作成する
+
+```ruby
+payment = client.create_payment(
+  order_code: "order-123",
+  amount: "100.00",
+  amount_type: "JPY",
+  color_theme: :light,
+  deadline: Time.now + 3600,
+  description: "Order #123"
+)
+
+payment.url
+payment.token
+```
+
+`amount` には `String`、`Integer`、または利用アプリケーションが `bigdecimal` を導入済みの場合は `BigDecimal` を指定できます。署名精度を曖昧にしないため `Float` は受け付けません。`amount` を省略すると、支払者が金額を決める支払いを作成します。
+
+`order_code` は Payment Request ごとに一意な ASCII 文字列を指定し、アプリケーション側で保存してください。
+
+## 支払いを取り消す
+
+```ruby
+client.cancel_payment(order_code: "order-123") #=> true
+```
+
+未払いかつ blockchain transaction が関連付けられていない支払いだけを取り消せます。すでに取消済みの場合も例外を返します。
+
+## Payment Result を検証する
+
+Web framework が受信した raw JSON body をそのまま渡します。
+
+```ruby
+result = client.verify_payment_result(raw_request_body)
+
+if result.success?
+  # order_code、amount、symbol を保存済み注文と照合して状態を更新する
+end
+```
+
+署名不一致時は `NodexPay::SignatureVerificationError`、JSON や field が不正な場合は `NodexPay::InvalidResponseError` を送出します。
+
+> [!WARNING]
+> Nodex Pay の署名対象は `order_code` と `amount` だけです。`result`、`symbol`、chain/transaction field の完全性や blockchain finality は署名だけでは保証されません。注文との照合、`transaction_code` の重複排除、必要に応じた on-chain 確認をアプリケーション側で行ってください。
+
+## エラー処理
+
+```ruby
+begin
+  client.create_payment(order_code: "order-123", amount: "100")
+rescue NodexPay::BadRequestError => error
+  warn "status=#{error.status} codes=#{error.error_codes.inspect}"
+rescue NodexPay::TimeoutError, NodexPay::TransportError => error
+  # 自動 retry はせず、結果不明として業務上の確認を行う
+end
+```
+
+POST の自動 retry と redirect 追従は行いません。API error の詳細は `status`、`error_codes`、`response_headers`、`response_body` から確認できます。response body は機密情報として扱い、そのままログへ出力しないでください。
+
+## 型定義
+
+RBS は `sig/nodex_pay.rbs`、Sorbet RBI は `rbi/nodex_pay.rbi` として gem に同梱しています。SDK 本体は `sorbet-runtime` に依存しません。
+
+標準の `srb tc` wrapper は、Bundler の依存に含まれる gem の `rbi/` を検出するため、追加の require やコピーは不要です。Tapioca で gem RBI を管理する project では、その project の Tapioca 更新フローに従ってください。
+
+RBI は `NodexPay::Client`、返却モデル、transport value、公開例外を型付けします。custom transport は duck typing のため `T.untyped` とし、`call(Request) -> Response` の契約は設計文書で定義しています。
+
+開発時の `bundle exec rake sorbet` はRBIを `typed: strict` で検査し、Sorbet metrics上のsignature coverage（`sig` 数 ÷ 検出method数）が100%でなければ失敗します。CIでも同じtaskを実行するため、型エラーや型定義の追加漏れを許容しません。
+
+## 開発
+
+```shell
+bundle install
+bundle exec rake
+bundle exec rake build
+```
+
+Testnet の資格情報を設定した場合に限り、支払い作成と取消の手動 smoke test を実行できます。
+
+```shell
+NODEX_PAY_IDENTIFICATION_TOKEN=... \
+NODEX_PAY_HASH_TOKEN=... \
+bundle exec rake smoke:testnet
+```
+
+この task は実際に Testnet の支払いを1件作成し、直後に取り消します。通信結果不明時の自動 retry は行いません。
+
+設計判断、wire contract、テスト戦略は [docs/README.md](docs/README.md) から参照できます。

data/docs/README.md

@@ -0,0 +1,49 @@
+# Nodex Pay Ruby SDK 設計文書
+
+このディレクトリは、Nodex Pay API の非公式 Ruby クライアント SDK `nodexpay` の設計仕様を管理します。実装者、レビュー担当者、SDK を組み込むアプリケーション開発者を対象としています。
+
+> [!IMPORTANT]
+> この SDK は Nodex Pay または Nodex Global Limited が提供・承認する公式 SDK ではありません。API の正確な挙動については、必ず Nodex Pay の公式ドキュメントと利用環境で確認してください。
+
+## 文書一覧
+
+| 文書 | 内容 |
+| --- | --- |
+| [architecture.md](architecture.md) | 公開 API、内部構造、モデル、transport、RBS/Sorbet RBI |
+| [api-contract.md](api-contract.md) | Payment Request / Cancel の wire contract と署名 |
+| [payment-results.md](payment-results.md) | Payment Result の解析、署名検証、セキュリティ境界 |
+| [http-and-errors.md](http-and-errors.md) | HTTP 動作、timeout、例外、エラーレスポンス |
+| [testing.md](testing.md) | テスト戦略、固定ベクトル、CI、testnet smoke test |
+| [implementation-plan.md](implementation-plan.md) | 実装順序、リリース条件、完了基準 |
+
+## 対象範囲
+
+初版では次の3つを扱います。
+
+- Nodex Pay へ支払いを作成する Payment Request API
+- 未払いの支払いを取り消す Payment Cancel API
+- 加盟店サーバーが受信する Payment Result の解析と署名検証
+
+Rails 固有の controller や routing、加盟店のデータベース、注文状態管理、加盟店が独自実装する Payment Status API は対象外です。
+
+## 用語
+
+| 用語 | 意味 |
+| --- | --- |
+| Business Client / 加盟店 | Nodex Pay を自サービスへ組み込む事業者 |
+| payer / 支払者 | Nodex Pay の支払い画面で支払いを実行する利用者 |
+| Identification Token | API body の `identification_token` として送る認証情報 |
+| Hash Token | SHA-256 値の生成に使う秘密情報。Nodex Pay へは送信しない |
+| Payment Result | 支払い結果確定時に Nodex Pay から加盟店へ送られる JSON POST |
+| wire value | HTTP body へ実際に書き込む文字列表現 |
+
+## 仕様の根拠と優先順位
+
+仕様は 2026-07-18 に確認しました。記載が食い違う場合は、次の順で判断します。
+
+1. 現行の [Payment Request API](https://nodex-pay.gitbook.io/docs/integration-guide/apis/payment-request-api.md)、[Payment Result API](https://nodex-pay.gitbook.io/docs/integration-guide/apis/payment-result-api.md)、[Payment Cancel API](https://nodex-pay.gitbook.io/docs/integration-guide/apis/payment-cancel-api.md)
+2. 現行の [Integration Guide](https://nodex-pay.gitbook.io/docs/integration-guide/integration-guide/implement-apis.md) と [Developer FAQ](https://nodex-pay.gitbook.io/docs/support/faq/developers-business-client-integrator.md)
+3. 公式ページに掲載された Ruby サンプル
+4. 前身サービスの公開サンプルは挙動調査の参考に限り、現行契約の根拠にはしない
+
+公式文書だけでは確定できない項目は、各文書で「公式記載」「SDK の採用判断」「Nodex 側への確認事項」に分けています。推測によるパラメーター追加や旧仕様へのフォールバックは行いません。

data/docs/api-contract.md

@@ -0,0 +1,203 @@
+# Outbound API 契約
+
+この文書は、Payment Request API と Payment Cancel API に対する SDK の wire contract を定義します。
+
+## 環境と endpoint
+
+| 環境 | Base URL | Payment Request | Payment Cancel |
+| --- | --- | --- | --- |
+| Production | `https://app.nodexpay.com/api/v1` | `POST /payment/receive` | `POST /payment/cancel` |
+| Testnet | `https://testnet.app.nodexpay.com/api/v1` | `POST /payment/receive` | `POST /payment/cancel` |
+
+`environment:` は `:production` または `:testnet` を必須とします。独自 base URL、別 domain への自動切り替え、到達不能時のフォールバックは提供しません。
+
+公式 Java サンプルにある `testnet.nodexpay.app.com` は、他のサンプルと一致せず証明書の host name とも一致しないため採用しません。旧 `slash.fi` domain も採用しません。
+
+## 共通 HTTP 形式
+
+SDK は現行公式 Ruby サンプルの `Net::HTTP.post_form` に合わせ、両 endpoint を `application/x-www-form-urlencoded` で送信します。
+
+```http
+Accept: application/json
+Content-Type: application/x-www-form-urlencoded
+User-Agent: nodexpay/<gem-version> ruby/<ruby-version>
+```
+
+Node.js の Integration Guide には JSON body の例もありますが、API ページは Content-Type を規定していません。Ruby SDK として wire format を一意にし、署名に用いた文字列がそのまま form field になることを優先します。
+
+## 認証と署名
+
+- `identification_token` は各 request body に含めます。
+- `hash_token` は SHA-256 の入力にのみ使い、request body や header へ含めません。
+- SHA-256 の出力は小文字16進文字列です。HMAC ではありません。
+- 区切り文字は ASCII の `::` です。
+
+金額がある Payment Request の署名対象:
+
+```text
+<order_code>::<normalized_amount>::<hash_token>
+```
+
+金額がない Payment Request と Payment Cancel の署名対象:
+
+```text
+<order_code>::::<hash_token>
+```
+
+## 共通 validation
+
+### `order_code`
+
+- String のみ
+- 空文字列は不可
+- ASCII の single-byte character のみ
+- 255 bytes 以下
+- 前後の空白を SDK が暗黙に除去しない
+
+Payment Request ごとに一意な値を利用者が生成・保存する必要があります。SDK は一意性を検査できません。同じ `order_code` の再送は error code 2021 になり得ますが、元の成功レスポンスを再取得できる冪等 API ではありません。
+
+### 金額の正規化
+
+`amount` は `String`、`Integer`、`BigDecimal` を受け付けます。`Float`、指数表記、NaN、Infinity、符号付きゼロは拒否します。
+
+正規化手順は次のとおりです。
+
+1. String は `\A(?:0|[1-9][0-9]*)(?:\.[0-9]+)?\z` に一致することを確認する。
+2. `BigDecimal` で値を検証する。
+3. 指数を使わない10進表記へ変換する。
+4. 小数部末尾の `0` を除去し、小数部がなくなった場合は小数点も除去する。
+5. 正規化後の同じ String を署名入力と form field に使う。
+
+例:
+
+| 入力 | wire value |
+| --- | --- |
+| `10` | `"10"` |
+| `"10.00"` | `"10"` |
+| `BigDecimal("10.50")` | `"10.5"` |
+| `"0.000001"` | `"0.000001"` |
+
+金額指定時の範囲は `0.000001..100000000`（両端を含む）です。公式説明にある “Zero or more” より、同じ field の詳細な範囲記載を優先します。
+
+## Payment Request
+
+### 公開メソッド
+
+```ruby
+client.create_payment(
+  order_code:,
+  amount: nil,
+  amount_type: nil,
+  color_theme: nil,
+  ui_mode: nil,
+  ext_description: nil,
+  deadline: nil,
+  description: nil
+) #=> NodexPay::Payment
+```
+
+### request field
+
+| Ruby keyword | Wire field | 必須 | 契約 |
+| --- | --- | --- | --- |
+| 内部設定 | `identification_token` | 必須 | 空でない String |
+| `order_code` | `order_code` | 必須 | 共通 validation に従う |
+| SDK 生成 | `verify_token` | 必須 | SHA-256 小文字 hex |
+| `amount` | `amount` | 任意 | 正規化済みの10進 String。nil 時は key 自体を省略 |
+| `color_theme` | `color_theme` | 任意 | `dark` または `light`。Symbol/String を小文字へ正規化 |
+| `amount_type` | `amount_type` | 任意 | 下記通貨。Symbol/String を大文字へ正規化 |
+| `ui_mode` | `uimode` | 任意 | `switchable` のみ |
+| `ext_description` | `ext_description` | 任意 | 有効な UTF-8、100 characters 以下 |
+| `deadline` | `deadline` | 任意 | `Time` または非負 Integer。Unix time 秒へ変換 |
+| `description` | `description` | 任意 | 有効な UTF-8、100 characters 以下 |
+
+`amount_type` の許可値:
+
+```text
+USD JPY EUR AED SGD HKD CAD IDR PHP INR KRW
+```
+
+SDK は `amount_type` が加盟店管理画面の設定と一致するかを確認できません。`deadline` が将来時刻かどうかも公式の client-side validation として規定されていないため、非負整数への変換だけを行います。
+
+### 成功レスポンス
+
+HTTP 200 で、次の JSON object を期待します。
+
+```json
+{
+  "url": "https://app.nodexpay.com/payment/PAYMENT_TOKEN",
+  "token": "PAYMENT_TOKEN",
+  "ext_reserved": "",
+  "ext_description": ""
+}
+```
+
+- `url` と `token` は必須の String として検査します。
+- `ext_reserved` と `ext_description` は欠落または null を許容し、String または nil として保持します。
+- 必須 field の欠落、型違い、JSON 以外の body は `InvalidResponseError` にします。
+- redirect URL へ SDK 自身がアクセスすることはありません。
+
+### `ext_reserved` と `callback_url`
+
+現行ページでは `ext_reserved` がレスポンス例、説明、error code 2101 に現れますが request table にありません。SDK はレスポンスを保持するだけで、`create_payment` の入力には追加しません。
+
+`callback_url` も error code 2040 にだけ現れ、現行 request table にはありません。旧仕様との互換性のために追加しません。
+
+## Payment Cancel
+
+### 公開メソッド
+
+```ruby
+client.cancel_payment(order_code:) #=> true
+```
+
+### request field
+
+| Wire field | 値 |
+| --- | --- |
+| `identification_token` | client の設定値 |
+| `order_code` | validation 済みの引数 |
+| `verify_token` | `SHA256("#{order_code}::::#{hash_token}")` |
+
+現行 Cancel schema には `amount` がありません。そのため署名は amount なしの形式へ固定し、公開メソッドにも amount 引数を設けません。
+
+### 成功レスポンス
+
+公式レスポンス例は具体的な schema を示していません。SDK は HTTP 200 だけを成功条件とし、body を解釈せず `true` を返します。
+
+HTTP 400 の代表的 error code:
+
+| Code | Name |
+| --- | --- |
+| 2010 | `RECEIVED_IDENTIFICATION_TOKEN_EMPTY` |
+| 2020 | `RECEIVED_ORDER_CODE_EMPTY` |
+| 2022 | `RECEIVED_ORDER_CODE_ALREADY_CANCELLED` |
+| 2023 | `PAYMENT_NOT_FOUND` |
+| 2024 | `PAYMENT_NOT_CANCELABLE` |
+| 2060 | `RECEIVED_VERIFY_TOKEN_EMPTY` |
+| 2061 | `RECEIVED_VERIFY_TOKEN_INVALID` |
+
+2022 は例外のまま利用者へ返します。SDK が状態を推測して成功へ変換することはありません。
+
+## 公式記載と採用判断
+
+| 論点 | 公式記載 | SDK の採用判断 |
+| --- | --- | --- |
+| outbound Content-Type | 未規定。form と JSON の例が混在 | 現行 Ruby サンプルに合わせ form-urlencoded |
+| amount 最小値 | “Zero or more” と `0.000001` が混在 | 詳細 field 定義の `0.000001` を採用 |
+| amount の文字列表現 | 言語別サンプルで `10`、`10.00`、`10.000000` | 送信前に一意に正規化し、署名と body で共有 |
+| Cancel の署名 | amount 有無の一般説明だが body に amount なし | amount なしの4連コロンを採用 |
+| `ext_reserved` | 入力説明があるが request table に field なし | 入力対象外、response のみ保持 |
+| 支払いの無効化 | 古い edge-case 文書は不可と記載 | 更新日の新しい Cancel API を優先 |
+
+## Nodex 側への確認事項
+
+1. Payment Request / Cancel が正式に保証する Content-Type
+2. server 側の amount 文字列処理と正規化規則
+3. Cancel の署名が常に amount なしであること
+4. Cancel 200 の実際の response body
+5. `ext_reserved` が現行 API の入力として利用可能か
+6. Testnet の Cancel endpoint と Production との差異
+
+これらは testnet contract test で確認します。確認前に推測した fallback や追加 keyword は実装しません。
+

data/docs/architecture.md

@@ -0,0 +1,226 @@
+# アーキテクチャ
+
+## 設計目標
+
+`nodexpay` は、Nodex Pay の3つの API 境界を小さく明示的な Ruby API として提供します。
+
+- 認証情報と環境をクライアントインスタンスへ閉じ込める
+- 金額の署名値と送信値を必ず同じ serializer から生成する
+- HTTP や JSON の詳細をモデルと例外へ変換する
+- Payment Result をフレームワーク非依存で検証する
+- Nodex Pay が規定していない再試行、状態管理、後方互換処理を追加しない
+
+## パッケージ識別子
+
+| 項目 | 値 |
+| --- | --- |
+| RubyGems 名 | `nodexpay` |
+| require path | `nodex_pay` |
+| Ruby 名前空間 | `NodexPay` |
+| 最低 Ruby | 3.4 |
+| ライセンス | MIT |
+| 位置づけ | 非公式 SDK |
+
+## 公開 API
+
+### クライアント生成
+
+```ruby
+require "nodex_pay"
+
+client = NodexPay::Client.new(
+  identification_token: ENV.fetch("NODEX_PAY_IDENTIFICATION_TOKEN"),
+  hash_token: ENV.fetch("NODEX_PAY_HASH_TOKEN"),
+  environment: :testnet,
+  open_timeout: 5,
+  read_timeout: 30,
+  write_timeout: 30,
+  transport: nil
+)
+```
+
+`identification_token`、`hash_token`、`environment` は必須です。環境の既定値は設けません。timeout の単位は秒で、正の数を受け付けます。`transport: nil` の場合は既定の `Net::HTTP` transport を使用します。
+
+クライアントは生成後に設定を変更できない immutable object とします。グローバルな `NodexPay.configure` は提供しません。
+
+### 支払い作成
+
+```ruby
+payment = client.create_payment(
+  order_code: "order-123",
+  amount: "100.00",
+  amount_type: "JPY",
+  color_theme: :light,
+  ui_mode: :switchable,
+  ext_description: "External extension data",
+  deadline: Time.now + 3600,
+  description: "Order #123"
+)
+
+payment.url             #=> "https://..."
+payment.token           #=> "..."
+payment.ext_reserved    #=> String or nil
+payment.ext_description #=> String or nil
+```
+
+`amount: nil` または省略時は、支払者が支払額を決める支払いを作成します。その他の入力契約は [api-contract.md](api-contract.md) で定義します。
+
+### 支払い取消
+
+```ruby
+client.cancel_payment(order_code: "order-123") #=> true
+```
+
+HTTP 200 のみを成功とし、それ以外は例外を送出します。すでに取消済みであることを示す error code 2022 も成功へ読み替えません。
+
+### Payment Result 検証
+
+```ruby
+result = client.verify_payment_result(raw_request_body)
+
+result.order_code
+result.transaction_code
+result.amount
+result.symbol
+result.result
+result.success?
+result.chain_id
+result.transaction_hash
+```
+
+引数は HTTP request の raw JSON body でなければなりません。JSON の解析、必須 field の型検査、署名検証に成功した場合だけ `PaymentResult` を返します。詳細は [payment-results.md](payment-results.md) で定義します。
+
+## 公開モデル
+
+モデルには Ruby の `Data` を使います。すべて immutable で、元の可変 Hash は保持しません。
+
+```ruby
+NodexPay::Payment = Data.define(
+  :url,
+  :token,
+  :ext_reserved,
+  :ext_description
+)
+
+NodexPay::PaymentResult = Data.define(
+  :order_code,
+  :transaction_code,
+  :amount,
+  :symbol,
+  :result,
+  :chain_id,
+  :transaction_hash
+) do
+  def success? = result
+end
+```
+
+`PaymentResult#amount` は `BigDecimal` へ変換せず、Nodex Pay が送信した文字列を保持します。これは署名検証に元の文字列表現が必要なためです。
+
+## データフロー
+
+### Outbound API
+
+```text
+Client
+  -> endpoint-specific validator
+  -> amount serializer
+  -> SHA-256 signer
+  -> form body encoder
+  -> Transport#call
+  -> status/error decoder
+  -> immutable model or exception
+```
+
+validation、金額変換、署名、response decoding は endpoint ごとに責務を分けます。汎用 Hash を組み立てて各層で再変換する設計は採用しません。
+
+### Payment Result
+
+```text
+raw JSON body
+  -> strict JSON parser
+  -> field/type validator
+  -> SHA-256 calculation
+  -> constant-time comparison
+  -> immutable PaymentResult
+```
+
+署名不一致時に未検証のモデルを返す API や `valid?: false` のような継続可能な結果は提供しません。
+
+## Transport インターフェース
+
+HTTP 実装の差し替え境界は次の2モデルと `call` メソッドだけです。
+
+```ruby
+NodexPay::Transport::Request = Data.define(
+  :method,
+  :uri,
+  :headers,
+  :body,
+  :open_timeout,
+  :read_timeout,
+  :write_timeout
+)
+
+NodexPay::Transport::Response = Data.define(
+  :status,
+  :headers,
+  :body
+)
+
+class CustomTransport
+  def call(request)
+    # NodexPay::Transport::Response を返す
+  end
+end
+```
+
+要件は次のとおりです。
+
+- `status` は Integer、`headers` は小文字 key の Hash、`body` は String を返す
+- transport は request body を再シリアライズしない
+- redirect、retry、response decoding を transport の責務に含めない
+- timeout と接続エラーは [http-and-errors.md](http-and-errors.md) の例外へ変換する
+
+`Request` と `Response` は transport 実装者向けの公開 extension interface とし、RBS に含めます。
+
+## スレッド安全性
+
+`Client`、設定値、モデル、request/response は生成後に変更しません。既定 transport はリクエスト間で可変な `Net::HTTP` connection を共有せず、呼び出しごとに接続を生成します。そのため1つの `Client` を複数スレッドから呼び出せます。
+
+利用者が注入する custom transport のスレッド安全性は、その transport 実装者の責任です。
+
+## 型定義
+
+### RBS
+
+`sig/nodex_pay.rbs` に次を収録します。
+
+- `Client` の initializer と3つの公開メソッド
+- 各 keyword 引数の union type
+- `Payment`、`PaymentResult`
+- transport の `Request`、`Response` と interface
+- すべての公開例外と属性
+
+### Sorbet RBI
+
+`rbi/nodex_pay.rbi` に RBS と同じ公開契約を収録し、gem package に同梱します。
+
+- `Client` の initializer と3つの公開メソッド
+- `Payment`、`PaymentResult`
+- transport の `Request`、`Response`、`NetHTTP#call`
+- すべての公開例外と `APIError` の属性
+
+Sorbet は structural interface を表現しないため、runtime に marker module を追加せず、custom transport 引数だけを `T.untyped` とします。transport の具体的な request/response と既定 `NetHTTP` は型付けします。
+
+標準の `srb tc` wrapper は Bundler の依存に含まれる gem の `rbi/` を自動検出します。Tapioca を使う project では、その project の gem RBI 更新フローに従います。SDK 本体は `sorbet-runtime` に依存せず、Sorbet は開発時の RBI 検証にだけ使用します。
+
+## 対象外
+
+- Rails/Rack の controller、middleware、routing
+- Webhook endpoint の HTTP response 生成
+- 注文・支払い状態の永続化
+- Webhook の重複排除や処理順制御
+- blockchain explorer / JSON-RPC による着金確認
+- 独自 base URL、proxy 設定、Faraday adapter
+- Nodex Pay の非公開または旧 API