digiwin_dsp 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0fd438c3029652103006f9fbb4b69c21abb7d699fb9e77234822e939660d710
-  data.tar.gz: 2b823c5afdb2452d18e2c22f9ad2111f1f0df5ab84862a400ba63a80b6c30bd2
+  metadata.gz: cf609190d9515001cb6540d2bbf8a88c8e1f6a5294ea21edbe1408bad4305fc4
+  data.tar.gz: 61f86d3485d0322c3bd0af81bddcdf0ae3105327d9de63a038dbab6854a3901b
 SHA512:
-  metadata.gz: 9695c0dea30adeced40a3b118ce95162dbd6cbcf0498ce30e82cd1d663107ae96a0dc0b57b54008eb7815d008a403efa1b73a915652d7d7ef488382982890ad5
-  data.tar.gz: 982922896540b5f6e5b2f7cbf2cdda02529bb4bbf89ee53005ea5030f0522b74407da2115547054b024a5dfae7caf175c46fc141e8006506e4f965ffdf8824fb
+  metadata.gz: 977f1b3a3e31e5de38b1bc48327ef5427cbedeb12b60949f1812c964a768fc96ab1810ca4b1aae7f4427c38b85c6fe108f296082ec0b202052bab76578901a31
+  data.tar.gz: 9301f03f1af6630147a6d1ad88fd7db41fdd70c329886b5b526a75bbf4f2492643852f353115f5c65e22c759656d1cb86708620d28199f3d9b4514360f69da90

data/CHANGELOG.md

@@ -6,6 +6,85 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-21
+
+### Fixed
+
+- **Envelope failure-message regexes now match anywhere in the string**
+  (dropped the `\A` anchor). Discovered via live UAT smoke test: DSP
+  prepends the offending `form_no` to `Message`, so the actual response
+  is e.g. `"ORDER-123:Duplicated:訂單不可重複"` rather than the
+  OpenAPI-example shape `"Duplicated:訂單不可重複"`. Previously the
+  prefix caused `DuplicateRequestError` / `RateLimitError` /
+  `ValidationError` / `ServerError` classifications to fall through to
+  generic `DigiwinDsp::Error`, defeating typed-rescue logic in callers.
+
+### Changed
+
+- CI CVE audit switched from the `bundler-audit` Ruby gem to the
+  `7a6163/gem-audit-action@v1` GitHub Action (which wraps the
+  `gem-audit` Rust binary). Faster, no runtime gem to keep updated, and
+  the action handles platform/version selection. Dropped `bundler-audit`
+  from the dev/test Gemfile group.
+- Rubocop now excludes `scripts/**/*` (operator scripts; not gem source).
+
+## [0.2.0] - 2026-05-21
+
+Security + correctness release. Addresses every HIGH and MEDIUM finding
+from the v0.1.x code review. Pre-1.0 SemVer; contains one breaking change.
+
+### BREAKING
+
+- **`DigiwinDsp::Error#response_body` removed.** Storing the full DSP
+  response on every exception leaked buyer PII (names, addresses, phone
+  numbers) to Sentry/Honeybadger/Rollbar via their default instance-var
+  serialization. Structured fields remain: `#code`, `#dsp_message`,
+  `#http_status`, `#request_id`. If you need the raw body, capture it in
+  your own Faraday middleware before the request reaches this gem.
+  **Migration:** delete any `e.response_body` access from rescue blocks.
+
+### Added
+
+- `Configuration#allowed_hosts` (default `["digiwindsp.digiwin.com"]`) —
+  SSRF allowlist enforced on `#base_url`. Extend it for proxy/mock setups:
+  `c.allowed_hosts += ["dsp-proxy.your-co.internal"]`.
+- CRLF (`\r` / `\n`) validation on `idempotency_key` and every entry of
+  the `headers:` kwarg in `Client#post`. Raises `ArgumentError` on
+  injection attempts (closes a header-smuggling vector that Faraday's
+  default adapter doesn't fully catch).
+- `bundler-audit` ~> 0.9 in dev/test + a CI step (`bundle-audit check
+  --update`) that fails on any known CVE in the locked dependency tree.
+
+### Changed
+
+- `Configuration#base_url` now validates the resolved URL:
+  - scheme MUST be `https` (no HTTP downgrade for the `DSP-api-key`)
+  - host MUST be in `allowed_hosts` (default: only `digiwindsp.digiwin.com`)
+  - malformed URIs raise `ConfigurationError`
+- Resources::{Order,Cancellation,Invoice,Return}#create now raise
+  `DigiwinDsp::ServerError` when DSP returns `Status:"Success"` without a
+  `response_detail` key, instead of returning `nil` (which became a
+  silent `NoMethodError` downstream).
+- Faraday retry now uses real exponential backoff with jitter
+  (`interval: 0.5, backoff_factor: 2, interval_randomness: 0.5`).
+  Previously `interval: 0, backoff_factor: 1` fired all three retries
+  instantly — actively counterproductive on 429 throttling.
+- Faraday `:json` middleware gains `parser_options: { max_nesting: 50 }`
+  as a DoS guard against hostile / malformed DSP responses.
+- `Resources::*.create` class-method shortcuts now declare typed kwargs
+  (`idempotency_key:`, `digi_header:`) so caller typos raise `ArgumentError`
+  at call time instead of being swallowed by `**`.
+- README configuration table distinguishes runtime-used settings from
+  reserved ones; calls out that `platform_id` lives in `request_detail`,
+  not auth headers; documents `allowed_hosts` + the proxy-override pattern.
+
+### Removed
+
+- `DigiwinDsp::Authenticator#auth_headers` no longer calls
+  `Configuration#validate!`. Validation was redundant (Client#post runs
+  it per-request) and silently skipped after construction-time mutation
+  due to connection memoization.
+
 ## [0.1.1] - 2026-05-21
 
 ### Added
@@ -26,7 +105,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [0.1.0] - 2026-05-21
 
-Initial release. Covers the four 自有官網模組 endpoints under `/v1/SalesOrder/*`.
+Initial release. Covers the four Self-hosted Website Module (自有官網模組) endpoints under `/v1/SalesOrder/*`.
 
 ### Added
 
@@ -61,6 +140,8 @@ Initial release. Covers the four 自有官網模組 endpoints under `/v1/SalesOr
 - The gem is **synchronous on purpose**. Callers wrap requests in their own background job runner (e.g. ActiveJob) when needed.
 - Idempotency: clients can send `X-Idempotency-Key` via the `idempotency_key:` kwarg. DSP also dedupes server-side by `form_no + platform_id`.
 
-[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/7a6163/digiwin_dsp/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/7a6163/digiwin_dsp/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/7a6163/digiwin_dsp/releases/tag/v0.1.0

data/README.md

@@ -5,14 +5,14 @@
 [![Ruby](https://img.shields.io/badge/ruby-%E2%89%A53.2-CC342D)](https://www.ruby-lang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE.txt)
 
-Ruby client for the Digiwin DSP **自有官網模組** (Official Website Module) API. Lets a Rails 自有官網 push orders, cancellations, invoice updates, and returns into the Digiwin ERP through the DSP gateway.
+Ruby client for the Digiwin DSP Self-hosted Website Module (自有官網模組) API. Lets your storefront push orders, cancellations, invoice updates, and returns into the Digiwin ERP through the DSP gateway.
 
 | Operation | Resource | Endpoint |
 |---|---|---|
-| 新增訂單 | `DigiwinDsp::Resources::Order` | `POST /v1/SalesOrder/add` |
-| 取消訂單 | `DigiwinDsp::Resources::Cancellation` | `POST /v1/SalesOrder/cancel` |
-| 發票更新 | `DigiwinDsp::Resources::Invoice` | `POST /v1/SalesOrder/invoice` |
-| 退貨 | `DigiwinDsp::Resources::Return` | `POST /v1/SalesOrder/return` |
+| Create order | `DigiwinDsp::Resources::Order` | `POST /v1/SalesOrder/add` |
+| Cancel order | `DigiwinDsp::Resources::Cancellation` | `POST /v1/SalesOrder/cancel` |
+| Invoice update | `DigiwinDsp::Resources::Invoice` | `POST /v1/SalesOrder/invoice` |
+| Return | `DigiwinDsp::Resources::Return` | `POST /v1/SalesOrder/return` |
 
 See [`docs/dsp-api-spec.md`](./docs/dsp-api-spec.md) (plus `docs/dsp-specs/*.yaml`) for the wire spec.
 
@@ -46,16 +46,17 @@ end
 
 Every setting also falls back to an ENV var:
 
-| Setting | ENV var | Default |
-|---|---|---|
-| `api_key` | `DIGIWIN_DSP_API_KEY` | _(required)_ |
-| `api_secret` | `DIGIWIN_DSP_API_SECRET` | `nil` |
-| `platform_id` | `DIGIWIN_DSP_PLATFORM_ID` | `nil` |
-| `environment` | `DIGIWIN_DSP_ENV` | `:sandbox` |
-| `base_url` | `DIGIWIN_DSP_BASE_URL` | resolved from `environment` |
-| `timeout` | — | `10` |
-| `open_timeout` | — | `5` |
-| `logger` | — | `Logger.new(IO::NULL)` |
+| Setting | ENV var | Default | Notes |
+|---|---|---|---|
+| `api_key` | `DIGIWIN_DSP_API_KEY` | _(required)_ | sent as `DSP-api-key` header |
+| `api_secret` | `DIGIWIN_DSP_API_SECRET` | `nil` | reserved for future HMAC signing; unused today |
+| `platform_id` | `DIGIWIN_DSP_PLATFORM_ID` | `nil` | sent **per-record** in `request_detail.platform_id` (not in auth headers) |
+| `environment` | `DIGIWIN_DSP_ENV` | `:sandbox` | `:sandbox` (UAT) or `:production` |
+| `base_url` | `DIGIWIN_DSP_BASE_URL` | resolved from `environment` | must be `https://` and have a host in `allowed_hosts` |
+| `allowed_hosts` | — | `["digiwindsp.digiwin.com"]` | SSRF allowlist; extend if you proxy DSP through a different domain |
+| `timeout` | — | `10` | seconds |
+| `open_timeout` | — | `5` | seconds |
+| `logger` | — | `Logger.new(IO::NULL)` | any Logger-like object |
 
 Base URLs (resolved from `environment`):
 
@@ -64,6 +65,21 @@ Base URLs (resolved from `environment`):
 
 See [`.env.local.example`](./.env.local.example) for a starter env file.
 
+### Custom proxy host
+
+If you front DSP with a corporate proxy or use a mock server, add the host:
+
+```ruby
+DigiwinDsp.configure do |c|
+  c.allowed_hosts += ["dsp-proxy.your-co.internal"]
+  c.base_url = "https://dsp-proxy.your-co.internal/api/DSP"
+end
+```
+
+Any host not in `allowed_hosts`, or any non-`https://` URL, raises
+`DigiwinDsp::ConfigurationError`. This is an SSRF + HTTP-downgrade guard
+since `DIGIWIN_DSP_BASE_URL` accepts arbitrary input.
+
 ## Usage
 
 Each resource exposes a single `#create(records, idempotency_key:, digi_header:)` method that returns the parsed `response_detail` array on success or raises a typed exception on failure.
@@ -75,7 +91,7 @@ record = {
   "platform_id"     => "acme_storefront_test",
   "create_datetime" => Time.now.strftime("%Y-%m-%d %H:%M:%S"),
   "site_no"         => "acme_storefront_test",
-  "form_no"         => "WEB202605200001",     # 官網訂單編號
+  "form_no"         => "WEB202605200001",     # storefront order number
   "order_date"      => "20260520",
   "buyer_name"      => "王小明",
   "receiver_name"   => "王小明",
@@ -92,7 +108,7 @@ record = {
   "price"           => "100",
   "subtotal"        => "100",
   "payment"         => "100",
-  "order_status"    => "3",                   # 3 = 新增
+  "order_status"    => "3",                   # 3 = new order
   "last_record"     => "Y"                    # "Y" on the final line
 }
 
@@ -151,7 +167,7 @@ end
 
 ## Error handling
 
-All exceptions inherit from `DigiwinDsp::Error` and carry rich attributes (`#code`, `#dsp_message`, `#http_status`, `#request_id`, `#response_body`).
+All exceptions inherit from `DigiwinDsp::Error` and carry structured attributes safe for logging: `#code`, `#dsp_message`, `#http_status`, `#request_id`. The raw response body is **intentionally not exposed** on exceptions to prevent PII leakage to error reporters like Sentry/Rollbar that serialize exception instance variables.
 
 | Exception | Raised when |
 |---|---|

data/lib/digiwin_dsp/authenticator.rb

@@ -8,8 +8,10 @@ module DigiwinDsp
       @configuration = configuration
     end
 
+    # Validation lives in Client#post (called per-request). Authenticator
+    # only ran validate! once per connection lifetime due to Client's
+    # memoized #default_headers, so the redundant call was misleading.
     def auth_headers
-      @configuration.validate!
       { HEADER_NAME => @configuration.api_key }
     end
   end

data/lib/digiwin_dsp/client.rb

@@ -6,6 +6,13 @@ require "faraday/retry"
 module DigiwinDsp
   class Client
     RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+    # Exponential backoff: ~0.5s, ~1s, ~2s between attempts, ±50% jitter so
+    # multiple Rails workers retrying the same upstream blip don't synchronize
+    # into a thundering herd against DSP.
+    RETRY_MAX = 3
+    RETRY_INTERVAL = 0.5
+    RETRY_BACKOFF_FACTOR = 2
+    RETRY_INTERVAL_RANDOMNESS = 0.5
     USER_AGENT = "digiwin_dsp/#{VERSION} (Faraday/#{Faraday::VERSION})".freeze
 
     STATUS_ERROR_MAP = {
@@ -16,13 +23,17 @@ module DigiwinDsp
       429 => RateLimitError
     }.freeze
 
-    # Order matters — more-specific patterns first.
+    # Patterns DSP returns in the response body's `Message` field on Status=Failure.
+    # The Chinese substrings are verbatim DSP responses — see docs/dsp-api-spec.md.
+    # Live DSP prepends the offending form_no to Message (e.g.
+    # "ORDER-123:Duplicated:訂單不可重複"), so we substring-match rather than
+    # anchor with \A. Order matters: more-specific patterns first.
     ENVELOPE_FAILURE_MAP = [
-      [/\ADuplicated:/, DuplicateRequestError],
-      [/\AProcessing:資料處理中/, RateLimitError],
-      [/\AProcessing:取消訂單處理中/, ValidationError],
-      [/\AWrongStatus:/, ValidationError],
-      [/\A系統異常:/, ServerError]
+      [/Duplicated:/, DuplicateRequestError], # order already exists
+      [/Processing:資料處理中/, RateLimitError], # transient; retry later
+      [/Processing:取消訂單處理中/, ValidationError], # cancel in flight
+      [/WrongStatus:/, ValidationError], # bad payload
+      [/系統異常:/, ServerError] # DSP internal error
     ].freeze
 
     def initialize(configuration: DigiwinDsp.configuration, authenticator: nil)
@@ -32,6 +43,7 @@ module DigiwinDsp
 
     def post(path, body, idempotency_key: nil, headers: {})
       @configuration.validate!
+      sanitize_request_headers!(idempotency_key, headers)
       response = connection.post(normalize_path(path)) do |req|
         req.headers["X-Idempotency-Key"] = idempotency_key if idempotency_key
         headers.each { |k, v| req.headers[k] = v }
@@ -48,12 +60,15 @@ module DigiwinDsp
       @connection ||= Faraday.new(url: connection_base_url, headers: default_headers) do |f|
         f.request :json
         f.request :retry,
-                  max: 3,
-                  interval: 0.0,
-                  backoff_factor: 1,
+                  max: RETRY_MAX,
+                  interval: RETRY_INTERVAL,
+                  backoff_factor: RETRY_BACKOFF_FACTOR,
+                  interval_randomness: RETRY_INTERVAL_RANDOMNESS,
                   retry_statuses: RETRY_STATUSES,
                   methods: %i[get post put patch delete]
-        f.response :json, content_type: /\bjson\z/
+        # max_nesting caps deserialization depth so a hostile / malformed DSP
+        # response can't allocate unbounded memory (DoS guard on the parser).
+        f.response :json, content_type: /\bjson\z/, parser_options: { max_nesting: 50 }
         f.response :logger, @configuration.logger, headers: false, bodies: false, log_level: :debug
         f.adapter Faraday.default_adapter
         f.options.timeout = @configuration.timeout
@@ -110,8 +125,7 @@ module DigiwinDsp
         code: hash["error_code"] || hash["code"],
         dsp_message: hash["error_message"] || hash["message"],
         request_id: hash["request_id"],
-        http_status: status,
-        response_body: body
+        http_status: status
       }
     end
 
@@ -120,9 +134,21 @@ module DigiwinDsp
         code: body["Status"],
         dsp_message: body["Message"],
         request_id: body["request_id"],
-        http_status: 200,
-        response_body: body
+        http_status: 200
       }
     end
+
+    # Block CRLF/LF/CR in header names and values. RFC 7230 §3.2.4 forbids
+    # them and Faraday + Net::HTTP catch many forms, but not all — close
+    # the gap to prevent header-injection / request-smuggling.
+    def sanitize_request_headers!(idempotency_key, headers)
+      sanitize_header!("X-Idempotency-Key", idempotency_key) if idempotency_key
+      headers.each { |k, v| sanitize_header!(k, v) }
+    end
+
+    def sanitize_header!(name, value)
+      raise ArgumentError, "invalid header value for #{name.inspect}: contains CRLF/LF/CR" if value.to_s.match?(/[\r\n]/)
+      raise ArgumentError, "invalid header name #{name.inspect}: contains CRLF/LF/CR" if name.to_s.match?(/[\r\n]/)
+    end
   end
 end

data/lib/digiwin_dsp/configuration.rb

@@ -1,45 +1,67 @@
 # frozen_string_literal: true
 
 require "logger"
+require "uri"
 
 module DigiwinDsp
   class Configuration
     DEFAULT_TIMEOUT = 10
     DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_ALLOWED_HOSTS = ["digiwindsp.digiwin.com"].freeze
 
     BASE_URLS = {
       sandbox: "https://digiwindsp.digiwin.com/DSP_UAT/api/DSP",
       production: "https://digiwindsp.digiwin.com/DSP/api/DSP"
     }.freeze
 
-    attr_accessor :api_key, :api_secret, :platform_id, :environment, :logger, :timeout, :open_timeout
+    attr_accessor :api_key, :api_secret, :platform_id, :environment, :logger,
+                  :timeout, :open_timeout, :allowed_hosts
     attr_writer :base_url
 
     def initialize
-      @api_key      = ENV["DIGIWIN_DSP_API_KEY"]
-      @api_secret   = ENV["DIGIWIN_DSP_API_SECRET"]
-      @platform_id  = ENV["DIGIWIN_DSP_PLATFORM_ID"]
-      @environment  = ENV.fetch("DIGIWIN_DSP_ENV") { "sandbox" }.to_sym
-      @base_url     = ENV["DIGIWIN_DSP_BASE_URL"]
-      @timeout      = DEFAULT_TIMEOUT
-      @open_timeout = DEFAULT_OPEN_TIMEOUT
-      @logger       = Logger.new(IO::NULL)
+      @api_key       = ENV["DIGIWIN_DSP_API_KEY"]
+      @api_secret    = ENV["DIGIWIN_DSP_API_SECRET"]
+      @platform_id   = ENV["DIGIWIN_DSP_PLATFORM_ID"]
+      @environment   = ENV.fetch("DIGIWIN_DSP_ENV") { "sandbox" }.to_sym
+      @base_url      = ENV["DIGIWIN_DSP_BASE_URL"]
+      @timeout       = DEFAULT_TIMEOUT
+      @open_timeout  = DEFAULT_OPEN_TIMEOUT
+      @logger        = Logger.new(IO::NULL)
+      @allowed_hosts = DEFAULT_ALLOWED_HOSTS.dup
     end
 
     def base_url
-      return @base_url if @base_url
+      url = @base_url || resolve_default_base_url
+      validate_url!(url)
+      url
+    end
+
+    def validate!
+      return unless api_key.nil? || api_key.to_s.empty?
+
+      raise ConfigurationError,
+            "api_key is required (set via DigiwinDsp.configure or DIGIWIN_DSP_API_KEY)"
+    end
+
+    private
 
+    def resolve_default_base_url
       BASE_URLS.fetch(environment) do
         raise ConfigurationError,
               "unknown environment #{environment.inspect}; expected one of #{BASE_URLS.keys.inspect}"
       end
     end
 
-    def validate!
-      return unless api_key.nil? || api_key.to_s.empty?
+    def validate_url!(url)
+      uri = URI.parse(url)
+      raise ConfigurationError, "base_url must use https (got #{uri.scheme.inspect})" unless uri.scheme == "https"
+      return if allowed_hosts.include?(uri.host)
 
       raise ConfigurationError,
-            "api_key is required (set via DigiwinDsp.configure or DIGIWIN_DSP_API_KEY)"
+            "base_url host #{uri.host.inspect} is not in allowed_hosts #{allowed_hosts.inspect}; " \
+            "add it via DigiwinDsp.configure { |c| c.allowed_hosts += [host] }"
+    rescue URI::InvalidURIError => e
+      raise ConfigurationError, "base_url is not a valid URI: #{e.message}"
     end
   end
 end

data/lib/digiwin_dsp/resources/cancellation.rb

@@ -5,8 +5,8 @@ module DigiwinDsp
     class Cancellation
       PATH = "/v1/SalesOrder/cancel"
 
-      def self.create(records, **)
-        new.create(records, **)
+      def self.create(records, idempotency_key: nil, digi_header: nil)
+        new.create(records, idempotency_key: idempotency_key, digi_header: digi_header)
       end
 
       def initialize(client = Client.new)
@@ -16,7 +16,9 @@ module DigiwinDsp
       def create(records, idempotency_key: nil, digi_header: nil)
         body = Serializers::CancellationSerializer.serialize(records, digi_header: digi_header)
         response = @client.post(PATH, body, idempotency_key: idempotency_key)
-        response["response_detail"]
+        response.fetch("response_detail") do
+          raise DigiwinDsp::ServerError, "DSP returned Status=Success without response_detail"
+        end
       end
     end
   end

data/lib/digiwin_dsp/resources/invoice.rb

@@ -5,8 +5,8 @@ module DigiwinDsp
     class Invoice
       PATH = "/v1/SalesOrder/invoice"
 
-      def self.create(records, **)
-        new.create(records, **)
+      def self.create(records, idempotency_key: nil, digi_header: nil)
+        new.create(records, idempotency_key: idempotency_key, digi_header: digi_header)
       end
 
       def initialize(client = Client.new)
@@ -16,7 +16,9 @@ module DigiwinDsp
       def create(records, idempotency_key: nil, digi_header: nil)
         body = Serializers::InvoiceSerializer.serialize(records, digi_header: digi_header)
         response = @client.post(PATH, body, idempotency_key: idempotency_key)
-        response["response_detail"]
+        response.fetch("response_detail") do
+          raise DigiwinDsp::ServerError, "DSP returned Status=Success without response_detail"
+        end
       end
     end
   end

data/lib/digiwin_dsp/resources/order.rb

@@ -5,8 +5,8 @@ module DigiwinDsp
     class Order
       PATH = "/v1/SalesOrder/add"
 
-      def self.create(records, **)
-        new.create(records, **)
+      def self.create(records, idempotency_key: nil, digi_header: nil)
+        new.create(records, idempotency_key: idempotency_key, digi_header: digi_header)
       end
 
       def initialize(client = Client.new)
@@ -16,7 +16,9 @@ module DigiwinDsp
       def create(records, idempotency_key: nil, digi_header: nil)
         body = Serializers::SalesOrderSerializer.serialize(records, digi_header: digi_header)
         response = @client.post(PATH, body, idempotency_key: idempotency_key)
-        response["response_detail"]
+        response.fetch("response_detail") do
+          raise DigiwinDsp::ServerError, "DSP returned Status=Success without response_detail"
+        end
       end
     end
   end

data/lib/digiwin_dsp/resources/return.rb

@@ -5,8 +5,8 @@ module DigiwinDsp
     class Return
       PATH = "/v1/SalesOrder/return"
 
-      def self.create(records, **)
-        new.create(records, **)
+      def self.create(records, idempotency_key: nil, digi_header: nil)
+        new.create(records, idempotency_key: idempotency_key, digi_header: digi_header)
       end
 
       def initialize(client = Client.new)
@@ -16,7 +16,9 @@ module DigiwinDsp
       def create(records, idempotency_key: nil, digi_header: nil)
         body = Serializers::ReturnSerializer.serialize(records, digi_header: digi_header)
         response = @client.post(PATH, body, idempotency_key: idempotency_key)
-        response["response_detail"]
+        response.fetch("response_detail") do
+          raise DigiwinDsp::ServerError, "DSP returned Status=Success without response_detail"
+        end
       end
     end
   end

data/lib/digiwin_dsp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DigiwinDsp
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 end

data/lib/digiwin_dsp.rb

@@ -4,15 +4,19 @@ require "zeitwerk"
 
 module DigiwinDsp
   class Error < StandardError
-    attr_reader :code, :dsp_message, :request_id, :http_status, :response_body
-
-    def initialize(message = nil, code: nil, dsp_message: nil, request_id: nil, http_status: nil, response_body: nil)
+    # NOTE: response_body is intentionally NOT exposed.
+    # Exception reporters (Sentry, Honeybadger, Rollbar, etc.) serialize
+    # instance variables by default; storing the raw DSP body would leak
+    # buyer PII (names, addresses, phone numbers) into third-party logging.
+    # Use the structured fields below for safe logging.
+    attr_reader :code, :dsp_message, :request_id, :http_status
+
+    def initialize(message = nil, code: nil, dsp_message: nil, request_id: nil, http_status: nil)
       super(message)
-      @code          = code
-      @dsp_message   = dsp_message
-      @request_id    = request_id
-      @http_status   = http_status
-      @response_body = response_body
+      @code        = code
+      @dsp_message = dsp_message
+      @request_id  = request_id
+      @http_status = http_status
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: digiwin_dsp
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Zac
@@ -52,8 +52,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
-description: Synchronous Ruby gem wrapping the Digiwin DSP 自有官網模組 endpoints (create
-  order, cancel order, invoice update, return) for use from a Rails site.
+description: Synchronous Ruby gem wrapping the Digiwin DSP Self-hosted Website Module
+  (自有官網模組) endpoints — create order, cancel order, invoice update, and return — for
+  use from a Rails storefront.
 email:
 - 579103+7a6163@users.noreply.github.com
 executables: []
@@ -102,5 +103,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Ruby client for the Digiwin DSP 自有官網模組 API.
+summary: Ruby client for the Digiwin DSP Self-hosted Website Module (自有官網模組) API.
 test_files: []