digiwin_dsp 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 813b05b6b115eed5a1fd308aa3c8a255da6df70afdf090101e7bfe0f74f605e7
-  data.tar.gz: 7ecfa001245bff0c95125f9667e303506ab9c1170bf8cce12f039c9773715bb4
+  metadata.gz: 39cfa7cd414965f7f63ac143177e2dcb4ec36dee5403a7fc211f7a6d782d4ad1
+  data.tar.gz: 86333bb27dd34ad93c350cdf2b195237faac24ca3c5192e843e4d43958c0c578
 SHA512:
-  metadata.gz: 1086238addb8b6feb861d80f4c133c9e891e4b64ed45821ffc0dd68bde3a8e0ea7fadd009ee2b34dfa78e9a640fe2b22d8590a1b364d80b43081688771b53ebd
-  data.tar.gz: 12079e2663087764b54acae5b774e22398dc9ec48b3379684bfd6fdb0be51ef2604ac7d2db30e59bb7a9dae6bfdbac62b965c5c29b1ac1c1c7bf0c8247ab9fb2
+  metadata.gz: 16f9fc374c1d7bb01d75f7963d616fb4fa26c649450700db75a54b7962756560371cb67f532d4afc06eb79f26d61561bbcfe94a376cd2f78f493814a364705d6
+  data.tar.gz: a6d881275de661e80a11ed41e0344bb1ec7848e681648c14c8449ddf38a1f153516c303ca36fd340c282fcf40748c1dbb44eade762aaf6adf371c13d7943e827

data/CHANGELOG.md

@@ -6,6 +6,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-22
+
+### BREAKING
+
+- **Date/time fields are format-checked before sending.** Every serializer now rejects malformed or impossible values (e.g. `20260230`, `25:00:00`) with `ValidationError`, per `docs/dsp-specs/*.yaml`: `create_datetime` `yyyy-MM-dd HH:mm:ss`; `order_date`, `invoice_date`, `order_expect_shipping_date` `YYYYMMDD`; `invoice_time` `HH:MM:SS`. Blank optional fields are skipped. **`invoice_time` without colons (`"123000"`) is now rejected** — DSP UAT accepted it, but the spec requires `HH:MM:SS` and DSP accepts invoice data unconditionally, so acceptance proved nothing about the ERP side. Values must be strings; `Time`/`Date` objects are rejected. The offending value is not echoed in the error message. Note: DSPOOFFICIAL001's `create_datetime` example uses slashes (`2024/01/10 04:48:45`), contradicting its own `yyyy-MM-dd HH:mm:ss` description; the slash form is rejected.
+
+### Changed
+
+- **HTTP 500, 502 and 504 are no longer retried.** A gateway error can arrive after DSP has already processed the POST, so resending risked a duplicate, or a spurious `DuplicateRequestError` on orders. They now raise `ServerError` right away. Only 429 and 503 are retried, plus pre-send connection failures.
+
+### Fixed
+
+- **`Client.new(base_url:)` is now checked against https + `allowed_hosts`.** The per-client override previously skipped the SSRF guard, so the API key could be sent to any host, even over plain http. `Configuration#validate_url!` is now public.
+- **`Webhooks.parse(nil, ...)` raises `Webhooks::ParseError`** instead of `TypeError`, which escaped `rescue DigiwinDsp::Error`.
+- **Serializers reject empty or non-Hash input** with `ValidationError`: `[]` used to be sent as an empty `request_detail`, and `nil` records raised `NoMethodError`.
+- **`allowed_hosts` matches hostnames case-insensitively**, so `https://DigiwinDSP.digiwin.com` is no longer rejected.
+
 ## [0.5.0] - 2026-10-01
 
 ### BREAKING
@@ -277,7 +294,8 @@ Initial release. Covers the four Self-hosted Website Module (自有官網模組)
 - 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.5.0...HEAD
+[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/7a6163/digiwin_dsp/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/7a6163/digiwin_dsp/compare/v0.4.2...v0.5.0
 [0.4.2]: https://github.com/7a6163/digiwin_dsp/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/7a6163/digiwin_dsp/compare/v0.4.0...v0.4.1

data/README.md

@@ -146,6 +146,8 @@ Each has its own required-field set (8 / 11 / 19 fields respectively). Inspect `
 DigiwinDsp::Serializers::CancellationSerializer::REQUIRED_FIELDS
 ```
 
+Date/time fields are format-checked locally on every endpoint (blank optional ones are skipped) and raise `ValidationError` if malformed: `create_datetime` → `"2026-05-20 12:00:00"`, `order_date` / `invoice_date` / `order_expect_shipping_date` → `"20260520"`, `invoice_time` → `"12:30:00"`. Pass strings, e.g. `t.strftime("%H:%M:%S")`; `Time`/`Date` objects are rejected.
+
 > ⚠️ **Invoice sync requires ERP-side customization.** Per DSPOOFFICIAL004's spec note (個案), DSP accepts your invoice data unconditionally, but it only becomes *visible inside the ERP* after Digiwin performs per-customer integration work. If invoices appear to sync successfully but the ERP team can't see them, this is why — confirm the customization with your Digiwin contact before debugging your own code.
 
 ### `order_status` enum
@@ -230,8 +232,8 @@ Every `Client#post` already retries transparently inside Faraday:
 | Setting | Value |
 |---|---|
 | Attempts | up to 4 (1 original + max 3 retries) |
-| Triggers | HTTP 429, 500, 502, 503, 504; connection failures that happen *before* the request reaches DSP (refused, host/network unreachable, DNS failure, connect timeout) |
-| Never retried | Read timeouts and mid-request connection resets — DSP may already have processed the POST, so resending could duplicate it. These raise `NetworkError`; check DSP state before retrying |
+| Triggers | HTTP 429, 503; connection failures that happen *before* the request reaches DSP (refused, host/network unreachable, DNS failure, connect timeout) |
+| Never retried | HTTP 500, 502, 504 (raise `ServerError`), read timeouts and mid-request connection resets (raise `NetworkError`) — DSP may already have processed the POST, so resending could duplicate it. Check DSP state before retrying |
 | Backoff | exponential — ~0.5s, ~1s, ~2s between attempts, ±50% jitter |
 
 So one `Resources::Order.create` call can take up to ~`4 × timeout + 3.5s` in the worst case (default `timeout` 10s → ~44s). **Size your job timeouts and queue latency budgets accordingly** — if you also add `retry_on` in ActiveJob/Sidekiq (recommended for `RateLimitError`, which DSP signals via the envelope and the gem does *not* retry internally), the two layers multiply.
@@ -261,11 +263,11 @@ All exceptions inherit from `DigiwinDsp::Error` and carry structured attributes
 | Exception | Raised when |
 |---|---|
 | `DigiwinDsp::ConfigurationError` | `api_key` missing at request time |
-| `DigiwinDsp::ValidationError` | Required field missing locally, or DSP returns `WrongStatus:` / `Processing:取消訂單處理中` / HTTP 400 |
+| `DigiwinDsp::ValidationError` | Required field missing or date/time field malformed locally, or DSP returns `WrongStatus:` / `Processing:取消訂單處理中` / HTTP 400 |
 | `DigiwinDsp::AuthenticationError` | HTTP 401 / 403 |
 | `DigiwinDsp::DuplicateRequestError` | DSP returns `Duplicated:` or HTTP 409 |
 | `DigiwinDsp::RateLimitError` | DSP returns `Processing:資料處理中` (retryable) or persistent HTTP 429 |
-| `DigiwinDsp::ServerError` | DSP returns `系統異常:` or HTTP 5xx that exhausts retries |
+| `DigiwinDsp::ServerError` | DSP returns `系統異常:` or HTTP 5xx (503 only after retries are exhausted) |
 | `DigiwinDsp::NetworkError` | TCP connect failure or timeout |
 | `DigiwinDsp::Error` | Catch-all (unmapped failure message or unexpected status) |
 
@@ -328,7 +330,7 @@ DigiwinDsp::Resources::Order.create(
 
 ```bash
 bin/setup              # bundle install
-bundle exec rspec      # run the full test suite (134 examples, 100% coverage)
+bundle exec rspec      # run the full test suite (100% line coverage)
 bundle exec rubocop    # lint
 bin/console            # IRB with the gem loaded
 ```

data/lib/digiwin_dsp/client.rb

@@ -5,7 +5,10 @@ require "faraday/retry"
 
 module DigiwinDsp
   class Client
-    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+    # Only statuses that mean "not processed". 500/502/504 are left out: a
+    # gateway error can arrive after DSP has already handled the POST, so a
+    # resend could duplicate it (same reasoning as read timeouts below).
+    RETRY_STATUSES = [429, 503].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.
@@ -102,7 +105,7 @@ module DigiwinDsp
     end
 
     def connection_base_url
-      base = @base_url_override || @configuration.base_url
+      base = @base_url_override&.tap { |url| @configuration.validate_url!(url) } || @configuration.base_url
       base.end_with?("/") ? base : "#{base}/"
     end
 

data/lib/digiwin_dsp/configuration.rb

@@ -62,8 +62,26 @@ module DigiwinDsp
             "api_key is required (set via DigiwinDsp.configure or DIGIWIN_DSP_API_KEY)"
     end
 
+    # Public so Client can apply the same https + allowed_hosts guard to a per-client base_url override.
+    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_host?(uri.host)
+
+      raise ConfigurationError,
+            "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
+
     private
 
+    # DNS hostnames are case-insensitive.
+    def allowed_host?(host)
+      !host.nil? && allowed_hosts.any? { |h| h.casecmp?(host) }
+    end
+
     def resolve_default_base_url
       BASE_URLS.fetch(environment) do
         raise ConfigurationError,
@@ -77,17 +95,5 @@ module DigiwinDsp
               "unknown environment #{environment.inspect}; expected one of #{WEBHOOK_BASE_URLS.keys.inspect}"
       end
     end
-
-    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,
-            "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/serializers/base.rb

@@ -1,10 +1,26 @@
 # frozen_string_literal: true
 
+require "date"
+
 module DigiwinDsp
   module Serializers
     # Mix into a serializer module via `extend Base`. The hosting module must
     # define a REQUIRED_FIELDS constant (array of string field names).
     module Base
+      # strftime formats from docs/dsp-specs/*.yaml. Checked on every endpoint
+      # whenever the field is present; blank optional fields are skipped.
+      FIELD_FORMATS = {
+        "create_datetime" => "%Y-%m-%d %H:%M:%S",
+        "order_date" => "%Y%m%d",
+        "invoice_date" => "%Y%m%d",
+        "order_expect_shipping_date" => "%Y%m%d",
+        "invoice_time" => "%H:%M:%S"
+      }.freeze
+
+      # Spec-style labels for error messages: "%Y-%m-%d" -> "YYYY-MM-DD".
+      # %m (month) and %M (minute) both read "MM", as in the DSP docs.
+      FORMAT_LABELS = { "%Y" => "YYYY", "%m" => "MM", "%d" => "DD", "%H" => "HH", "%M" => "MM", "%S" => "SS" }.freeze
+
       def serialize(records, digi_header: nil)
         normalized = normalize(records)
         validate!(normalized)
@@ -15,24 +31,47 @@ module DigiwinDsp
 
       def normalize(records)
         list = records.is_a?(Array) ? records : [records]
+        raise ValidationError, "records must not be empty" if list.empty?
+        # respond_to? rather than is_a?(Hash) so ActionController::Parameters keeps working.
+        raise ValidationError, "each record must be a Hash" unless list.all? { |r| r.respond_to?(:transform_keys) }
+
         list.map { |r| r.transform_keys(&:to_s) }
       end
 
       def validate!(records)
-        problems = []
-        total = records.size
-        total.times { |i| problems.concat(missing_fields(records[i], i, total)) }
-        return if problems.empty?
+        prefixes = records.size > 1 ? records.each_index.map { |i| "[#{i}]." } : [""]
+        pairs = records.zip(prefixes)
+        missing = pairs.flat_map { |r, pre| missing_fields(r, pre) }
+        invalid = pairs.flat_map { |r, pre| invalid_formats(r, pre) }
+        return if missing.empty? && invalid.empty?
 
-        raise ValidationError, "missing or empty required fields: #{problems.join(", ")}"
+        raise ValidationError, validation_message(missing, invalid)
       end
 
-      def missing_fields(record, index, total)
-        missing = self::REQUIRED_FIELDS.reject { |f| present?(record[f]) }
-        return [] if missing.empty?
+      def missing_fields(record, prefix)
+        self::REQUIRED_FIELDS.reject { |f| present?(record[f]) }.map { |f| "#{prefix}#{f}" }
+      end
+
+      # The offending value stays out of the message, matching the PII rule on errors.
+      def invalid_formats(record, prefix)
+        FIELD_FORMATS.filter_map do |field, format|
+          value = record[field]
+          "#{prefix}#{field} (expected #{format.gsub(/%[YmdHMS]/, FORMAT_LABELS)})" if present?(value) && !valid_format?(value, format)
+        end
+      end
+
+      # The strftime round-trip rejects what strptime tolerates: "2026-5-20", "20260520 ", "24:00:00".
+      def valid_format?(value, format)
+        value.is_a?(String) && DateTime.strptime(value, format).strftime(format) == value
+      rescue Date::Error
+        false
+      end
 
-        prefix = total > 1 ? "[#{index}]." : ""
-        missing.map { |f| "#{prefix}#{f}" }
+      def validation_message(missing, invalid)
+        parts = []
+        parts << "missing or empty required fields: #{missing.join(", ")}" if missing.any?
+        parts << "invalid format: #{invalid.join(", ")}" if invalid.any?
+        parts.join("; ")
       end
 
       def present?(value)

data/lib/digiwin_dsp/version.rb

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

data/lib/digiwin_dsp/webhooks/event.rb

@@ -21,6 +21,9 @@ module DigiwinDsp
         JSON.parse(raw_body, max_nesting: 50)
       rescue JSON::ParserError => e
         raise ParseError, "invalid JSON: #{e.message}"
+      rescue TypeError
+        # A nil / non-String body (e.g. missing raw_post) must stay inside the DigiwinDsp::Error tree.
+        raise ParseError, "raw body must be a String (got #{raw_body.class})"
       end
 
       def self.extract_request(hash)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: digiwin_dsp
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Zac
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday