digiwin_dsp 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a72275c796b57bd858c4d7c5a67b7074e2738985ae92a9011836c0db9383321
-  data.tar.gz: 78db9041211bbc64cf7b9cb9cbfccb5f1dbef00efbfc4d5aa7b7a9e44d458f63
+  metadata.gz: 8b74fbc1739d80f99a563f002be9ab06212eb0ffce531ddf9144c9c8ceb28b34
+  data.tar.gz: 363e1faecee60d9a4c8f5cfe03b00bf2febd35f015f0034451e1c9c9e191308a
 SHA512:
-  metadata.gz: 82cc7dbb4ca9194b851ee1bdcd853fc6c084d13ae41d6d1c38ebefec8fba80be722bf40e77e332db7ef1e821aec8d8522358740bcd4531e21744fcb66844f9fa
-  data.tar.gz: ba67eb5115c8aa4d978b71f52c1ac063eb2643bdaccdfa30cb9ed3f3dfd1022b3378497c04cfc468d317a211453d983751ce2cfba635eeceb6d9e8c98044655c
+  metadata.gz: b14060dbe2c6d65890ffb925c1ee9f499a7870db0c4eb301646eaf0ea2907869e0e331d8ff14b76e1a6bd474a2de5bf75f97d9bdf5073d856a5c55b6753dd225
+  data.tar.gz: 1f1f7ab22cd0e077e455ce7cc6451442e5285ccf7e1c94a1abcb0c6e284e3fc86f94cf879170b4ddd2cc3d747ca532ba64a6082bf89be972aacadef23df33e7c

data/CHANGELOG.md

@@ -6,6 +6,52 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-12
+
+Ergonomics + cleanup release. One breaking change (dead config removal).
+
+### BREAKING
+
+- **`Configuration#api_secret` removed** (accessor, `DIGIWIN_DSP_API_SECRET` ENV read, README row, `.env.local.example` line). Reserved since v0.1.0 for "future HMAC signing" — DSPOOFFICIAL100 confirmed DSP doesn't sign webhooks, no gem code ever read it, and advertising it implied a security mechanism that didn't exist. **Migration:** delete `c.api_secret = ...` from your configure block (it would now raise `NoMethodError` at boot); a lingering ENV var is harmless.
+
+### Added
+
+- **`DigiwinDsp::Enums`** — DSP code tables as Ruby constants so callers stop hardcoding `"9104"`:
+  `OrderStatus`, `PayType` (15), `ShippingType` (9), `InvoiceStatus` (5), `InvoiceType` (10), `CarrierType` (5), `IsPay`, plus inbound-webhook `UpdateMode` and `DistributorCode`. Each has a frozen `ALL` array for caller-side validations. No forced client-side validation — DSP still rejects unknown codes via `WrongStatus:` → `ValidationError`.
+- **Unknown-envelope warning.** If a 2xx Hash body matches neither known envelope shape (`Status/Message` nor `std_data.execution`), `Client` now `logger.warn`s before passing it through — so if DSP ships a third envelope, failures can't silently read as success.
+- **Multi-line `last_record` live-verified.** A 2-line order with `"N"` on the non-final line was accepted by UAT (2026-06-12). The YAML spec's "blank means not-last" alternative conflicts with the gem's required-field check; the documented `"N"` convention is now the verified path.
+
+### Changed
+
+- `WebhookSubscription::ACTIONS` now derives from `Webhooks::ACTION_REGISTRY.keys` — what you can subscribe to is exactly what the gem can parse (single source of truth; previously two parallel lists that could drift).
+
+### Docs
+
+- README gains a **Troubleshooting / FAQ** section (HTTP-200-failure gotcha, `序號驗證失敗`, `SalesNotCreate` timing, `Shipped:` permanence, `WrongStatus` self-correction, dedupe-on-`form_no` surprises, webhook-delivery checklist, ERP invoice-visibility caveat).
+- README documents the **built-in Faraday retry** (up to 4 attempts, exponential backoff + jitter) and how it stacks with ActiveJob/Sidekiq retries — worst-case latency math included.
+- README flags DSPOOFFICIAL004's 個案 caveat: invoice data is only visible inside the ERP after per-customer Digiwin customization.
+
+## [0.3.1] - 2026-06-12
+
+Hardening patch from a full gem + docs review. All fixes grounded in the vendor YAML specs.
+
+### Fixed
+
+- **TLS failures now raise `DigiwinDsp::NetworkError`.** `Faraday::SSLError` sits directly under `Faraday::Error` (not `ConnectionFailed`), so certificate problems previously leaked as raw Faraday exceptions that `rescue DigiwinDsp::Error` could not catch.
+- **Three more DSP failure messages classify into typed exceptions** instead of falling through to generic `Error`:
+  - `Shipped:訂單已出貨，不可取消` (DSPOOFFICIAL002) → `ValidationError` — permanent; the order left the warehouse
+  - `Processing:新增訂單處理中，不可取消` (DSPOOFFICIAL002) → `RateLimitError` — retryable once ERP processes the add
+  - `SalesNotCreate:銷貨單未成立` (DSPOOFFICIAL004) → `RateLimitError` — retryable once ERP converts the sales doc
+  Sidekiq/ActiveJob retry strategies can now distinguish "don't retry" from "retry later" on cancel and invoice flows.
+- **`Webhooks::Event.parse_json` / `.extract_request` are now private class methods.** They were internal helpers accidentally exposed on all three event classes.
+- **`WebhookSubscription` rejects non-`https://` callback addresses** at registration time. DSPOOFFICIAL100 mandates HTTPS callbacks, and with no HMAC signing a plaintext callback would be indefensible. (Previously the README claimed this was enforced when it wasn't.)
+
+### Docs
+
+- `dsp-api-spec.md`: corrected the e-invoice carrier field name — `Resources::Invoice` sends **`carrier_type`** (DSPOOFFICIAL004:164), not `carrier_code`. `carrier_code` is only on `Resources::Order` and the inbound webhook. Optional fields aren't validated client-side, so the wrong name silently drops carrier data.
+- `dsp-api-spec.md`: failure-message table now covers 002 (cancel) and 004 (invoice) sources, not just 001.
+- README: webhook security bullet now describes the actual https enforcement.
+
 ## [0.3.0] - 2026-05-28
 
 DSP webhook support (DSPOOFFICIAL100). Lets a Rails app register a callback URL with DSP, then receive and parse the three documented ERP-originated push events: inventory updates, shipping/logistics status, and invoice issuance.
@@ -205,7 +251,9 @@ 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.3.0...HEAD
+[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/7a6163/digiwin_dsp/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/7a6163/digiwin_dsp/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.4...v0.3.0
 [0.2.4]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.2...v0.2.3

data/README.md

@@ -51,7 +51,6 @@ Every setting also falls back to an ENV var:
 | 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` |
@@ -119,7 +118,7 @@ response_detail = DigiwinDsp::Resources::Order.create(record)
 # => [{ "form_no" => "WEB202605200001", ... }]
 ```
 
-Multi-line orders: pass an array. Each element must carry the order-level fields plus its own line fields. Set `"last_record" => "Y"` on the final element and `"N"` on the rest:
+Multi-line orders: pass an array. Each element must carry the order-level fields plus its own line fields. Set `"last_record" => "Y"` on the final element and `"N"` on the rest (live-verified against UAT 2026-06-12; the YAML spec says blank means "not last", but the gem's required-field check rejects blanks and DSP accepts the explicit `"N"`):
 
 ```ruby
 records = [
@@ -144,6 +143,8 @@ Each has its own required-field set (8 / 11 / 19 fields respectively). Inspect `
 DigiwinDsp::Serializers::CancellationSerializer::REQUIRED_FIELDS
 ```
 
+> ⚠️ **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
 
 Each endpoint requires a specific `order_status` value inside `request_detail`. DSP rejects others with `WrongStatus:order_status錯誤，請固定給N(...)`. The OpenAPI examples don't document this — verified live against UAT 2026-05-21:
@@ -213,12 +214,26 @@ end
 ```
 
 > ⚠️ **DSP does NOT sign inbound webhooks.** There is no HMAC header. Defend the callback endpoint with:
-> - HTTPS-only (the gem's `address` validation requires this implicitly via `allowed_hosts` if you register through it)
+> - HTTPS-only — `WebhookSubscription` rejects non-`https://` addresses at registration time (DSP's own spec mandates HTTPS callbacks)
 > - An unguessable URL path (treat it as a secret)
 > - An IP allowlist for DSP's egress range if your network team can get one
 > - Replying `200 OK` within 30 seconds (DSP will retry and may eventually block your endpoint if too many calls fail)
 > - **Idempotency by `form_no` / `invoice_number` / etc. on your side** — DSP may retry the same event
 
+### Built-in retry (read before stacking job retries)
+
+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 |
+| 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.
+
+The built-in retry covers transport-level blips; envelope-level "retry later" signals (`Processing:資料處理中`, `SalesNotCreate:` etc. → `RateLimitError`) are deliberately left to your job layer, where you control scheduling.
+
 ### Background jobs
 
 The gem is synchronous on purpose. Wrap calls in your own job runner:
@@ -265,6 +280,32 @@ rescue DigiwinDsp::RateLimitError, DigiwinDsp::ServerError
 end
 ```
 
+## Troubleshooting / FAQ
+
+**"My request succeeded with HTTP 200 but raised an exception?"**
+That's DSP's design — application failures come back as HTTP 200 with `Status:"Failure"` in the body. The gem parses the envelope and raises the matching typed exception. Trust the exception, not the HTTP status.
+
+**`AuthenticationError: DSP 序號驗證失敗`**
+Your `DSP-api-key` is wrong, expired, or for the other environment (UAT keys don't work on production and vice versa). Note this arrives as HTTP 200, not 401.
+
+**`RateLimitError: ...SalesNotCreate:銷貨單未成立`** (invoice sync)
+The ERP hasn't converted the order into a sales document yet — this is a timing issue, not a bug. Retry later (the exception type is retryable by design). If it persists for hours, ask your Digiwin contact whether order conversion is running.
+
+**`ValidationError: ...Shipped:訂單已出貨，不可取消`** (cancel)
+Permanent — the order left the warehouse. Don't retry; surface to your support flow instead.
+
+**`ValidationError: ...WrongStatus:order_status錯誤，請固定給N(...)`**
+You sent the wrong `order_status` for that endpoint. DSP's message tells you the expected value; or just use `DigiwinDsp::Enums::OrderStatus` constants.
+
+**`DuplicateRequestError` on a brand-new order**
+DSP dedupes on `form_no + platform_id` forever — including orders created in earlier tests. Generate unique `form_no` values per environment.
+
+**Inventory webhook never arrives**
+Webhook delivery requires (1) a successful `WebhookSubscription.create` for that exact `action`, (2) an HTTPS endpoint answering `200` within 30s, and (3) the ERP actually emitting the event. Check all three, in that order.
+
+**Invoices sync but the ERP team can't see them**
+See the invoice caveat above — DSPOOFFICIAL004 requires per-customer ERP customization (個案) before invoice data is visible in the ERP.
+
 ## Custom `digi_header`
 
 By default the gem **omits `digi_header`** from the request body (it's only required for certain custom Digiwin integrations). If your DSP setup expects one, pass it through:

data/lib/digiwin_dsp/client.rb

@@ -33,6 +33,9 @@ module DigiwinDsp
       [/Duplicated:/, DuplicateRequestError], # order already exists
       [/Processing:資料處理中/, RateLimitError], # transient; retry later
       [/Processing:取消訂單處理中/, ValidationError], # cancel in flight
+      [/Processing:新增訂單處理中/, RateLimitError], # add in flight; cancel retryable after ERP processes (002)
+      [/Shipped:/, ValidationError], # already shipped — cancel permanently impossible (002)
+      [/SalesNotCreate:/, RateLimitError], # ERP hasn't converted sales doc yet; invoice retryable (004)
       [/WrongStatus:/, ValidationError], # bad payload
       [/系統異常:/, ServerError] # DSP internal error
     ].freeze
@@ -52,7 +55,10 @@ module DigiwinDsp
         req.body = body
       end
       handle_response(response)
-    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => e
+      # SSLError sits directly under Faraday::Error (not ConnectionFailed),
+      # so it needs an explicit entry — otherwise TLS failures leak as raw
+      # Faraday exceptions that `rescue DigiwinDsp::Error` won't catch.
       raise NetworkError, e.message
     end
 
@@ -126,11 +132,25 @@ module DigiwinDsp
         return nil if exec["code"].to_s == "0"
 
         { message: exec["description"].to_s, code: exec["code"] }
-      elsif body["Status"].to_s.casecmp("failure").zero?
+      elsif body.key?("Status")
+        return nil unless body["Status"].to_s.casecmp("failure").zero?
+
         { message: body["Message"].to_s, code: body["Status"] }
+      else
+        warn_unknown_envelope(body)
+        nil
       end
     end
 
+    # Neither known envelope. If DSP ships a third shape, failures would
+    # otherwise pass through as "success" silently — leave a trace.
+    def warn_unknown_envelope(body)
+      @configuration.logger.warn(
+        "digiwin_dsp: response matched no known envelope shape " \
+        "(keys: #{body.keys.inspect}); passing body through unchanged"
+      )
+    end
+
     def classify_envelope_failure(message, code:, body:)
       klass = ENVELOPE_FAILURE_MAP.find { |regex, _| regex.match?(message) }&.last || Error
       klass.new(message, code: code, dsp_message: message, request_id: body["request_id"], http_status: 200)

data/lib/digiwin_dsp/configuration.rb

@@ -21,13 +21,12 @@ module DigiwinDsp
       production: "https://digiwindsp.digiwin.com/DSP/api/webhook"
     }.freeze
 
-    attr_accessor :api_key, :api_secret, :platform_id, :environment, :logger,
+    attr_accessor :api_key, :platform_id, :environment, :logger,
                   :timeout, :open_timeout, :allowed_hosts
     attr_writer :base_url, :webhook_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"]

data/lib/digiwin_dsp/enums.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  # DSP wire-format code tables as Ruby constants, so callers write
+  # `Enums::PayType::CREDIT_CARD` instead of a bare "9104".
+  #
+  # Source of truth: docs/dsp-specs/*.yaml (see docs/dsp-api-spec.md for the
+  # readable digest). The gem deliberately does NOT validate these values
+  # client-side — DSP rejects unknown codes with `WrongStatus:` →
+  # `ValidationError`. The `ALL` arrays exist for caller-side checks
+  # (e.g. dropdowns, model validations) if you want them.
+  module Enums
+    # request_detail.order_status — fixed per endpoint (live-verified).
+    module OrderStatus
+      CANCEL    = "2"  # Resources::Cancellation
+      NEW_ORDER = "3"  # Resources::Order
+      INVOICE   = "5"  # Resources::Invoice
+      RETURN    = "7"  # Resources::Return
+
+      ALL = [CANCEL, NEW_ORDER, INVOICE, RETURN].freeze
+    end
+
+    # request_detail.pay_type on Resources::Order (DSPOOFFICIAL001:163-179).
+    module PayType
+      OTHER                   = "9100" # 其他收款方式
+      JKO_PAY                 = "9101" # 街口支付
+      CVS_COD                 = "9102" # 超商取貨付款
+      GOOGLE_PAY              = "9103"
+      CREDIT_CARD             = "9104" # 信用卡一次付款
+      CASH_ON_DELIVERY        = "9105" # 貨到付款
+      AFTEE                   = "9106" # AFTEE 先享後付
+      APPLE_PAY               = "9107"
+      ATM                     = "9108" # ATM 付款
+      CREDIT_CARD_INSTALLMENT = "9109" # 信用卡分期付款
+      EASY_WALLET             = "9110" # 悠遊付
+      LINE_PAY                = "9111"
+      PAYPAL_EXPRESS          = "9112"
+      FREE_CHECKOUT           = "9113" # 免費結帳
+      CVS_PAYMENT_CODE        = "9114" # 超商代碼繳費
+
+      ALL = [OTHER, JKO_PAY, CVS_COD, GOOGLE_PAY, CREDIT_CARD, CASH_ON_DELIVERY,
+             AFTEE, APPLE_PAY, ATM, CREDIT_CARD_INSTALLMENT, EASY_WALLET,
+             LINE_PAY, PAYPAL_EXPRESS, FREE_CHECKOUT, CVS_PAYMENT_CODE].freeze
+    end
+
+    # request_detail.shipping_type on Resources::Order (DSPOOFFICIAL001:186-200).
+    module ShippingType
+      OTHER              = "9100" # 其他取貨方式
+      INTERNATIONAL      = "9101" # 海外宅配
+      HOME_DELIVERY_COD  = "9102" # 宅配貨到付款
+      STORE_PICKUP_PAID  = "9103" # 付款後門市自取
+      HOME_DELIVERY_PAID = "9104" # 宅配(含離島)已付款只取貨
+      CVS_PICKUP_PAID    = "9105" # 付款後超商取貨
+      CVS_PICKUP_COD     = "9106" # 超商取貨付款
+      HOME_DELIVERY_CASH = "9107" # 宅配(含離島)貨到付現
+      HOME_DELIVERY_CARD = "9108" # 宅配(含離島)貨到刷卡
+
+      ALL = [OTHER, INTERNATIONAL, HOME_DELIVERY_COD, STORE_PICKUP_PAID,
+             HOME_DELIVERY_PAID, CVS_PICKUP_PAID, CVS_PICKUP_COD,
+             HOME_DELIVERY_CASH, HOME_DELIVERY_CARD].freeze
+    end
+
+    # request_detail.invoice_status on Resources::Invoice (DSPOOFFICIAL004:110-122).
+    module InvoiceStatus
+      ISSUED           = "1" # 開立
+      VOIDED           = "2" # 作廢
+      ALLOWANCE        = "3" # 折讓
+      CANCELLED        = "4" # 註銷
+      ALLOWANCE_VOIDED = "5" # 折讓作廢
+
+      ALL = [ISSUED, VOIDED, ALLOWANCE, CANCELLED, ALLOWANCE_VOIDED].freeze
+    end
+
+    # request_detail.invoice_type on Resources::Invoice (DSPOOFFICIAL004:123-140).
+    module InvoiceType
+      DUPLICATE           = "1" # 二聯式
+      TRIPLICATE          = "2" # 三聯式
+      DUPLICATE_REGISTER  = "3" # 二聯式收銀機發票
+      TRIPLICATE_REGISTER = "4" # 三聯式收銀機發票
+      COMPUTER            = "5" # 電子計算機發票
+      EXEMPT              = "6" # 免用統一發票
+      E_INVOICE           = "7" # 電子發票 — modern default in Taiwan
+      CHINA_VAT_SPECIAL   = "A" # 增值稅專用發票
+      CHINA_GENERAL       = "B" # 普通發票
+      CHINA_EXEMPT        = "C" # 免用發票
+
+      ALL = [DUPLICATE, TRIPLICATE, DUPLICATE_REGISTER, TRIPLICATE_REGISTER,
+             COMPUTER, EXEMPT, E_INVOICE, CHINA_VAT_SPECIAL, CHINA_GENERAL,
+             CHINA_EXEMPT].freeze
+    end
+
+    # E-invoice carrier codes (DSPOOFFICIAL004:167-176). ⚠️ Field name varies:
+    # `carrier_type` on Resources::Invoice, `carrier_code` on Resources::Order
+    # and the inbound Webhooks::InvoiceUpdate payload.
+    module CarrierType
+      IPASS          = "1H0001" # 一卡通
+      EASYCARD       = "1K0001" # 悠遊卡
+      ICASH          = "2G0001"
+      MOBILE_BARCODE = "3J0002" # 手機條碼 — most common
+      CITIZEN_CERT   = "CQ0001" # 自然人憑證
+
+      ALL = [IPASS, EASYCARD, ICASH, MOBILE_BARCODE, CITIZEN_CERT].freeze
+    end
+
+    # request_detail.is_pay on Resources::Invoice (DSPOOFFICIAL004:189-195).
+    module IsPay
+      UNPAID = "0"
+      PAID   = "1"
+
+      ALL = [UNPAID, PAID].freeze
+    end
+
+    # spec_list[].update_mode on inbound Webhooks::InventoryUpdate
+    # (DSPOOFFICIAL100). "adjust" requires per-customer ERP customization.
+    module UpdateMode
+      TOTAL  = "total"  # stock is the new total
+      ADJUST = "adjust" # stock is a delta (can be negative)
+
+      ALL = [TOTAL, ADJUST].freeze
+    end
+
+    # distributor_code on inbound Webhooks::LogisticsUpdate (DSPOOFFICIAL100).
+    # Spec lists only these two; handle unknown carriers defensively.
+    module DistributorCode
+      HCT = "HCT" # 新竹倉儲
+      CAT = "CAT" # 統一速達(黑貓)
+
+      ALL = [HCT, CAT].freeze
+    end
+  end
+end

data/lib/digiwin_dsp/resources/webhook_subscription.rb

@@ -12,11 +12,9 @@ module DigiwinDsp
     class WebhookSubscription
       PATH = "/v1/webhook"
       DEFAULT_PROD = "OFFICIALWEBSITE"
-      ACTIONS = %w[
-        product/inventory_update
-        wms/logistics/package/update
-        invoice/update
-      ].freeze
+      # Single source of truth lives in Webhooks::ACTION_REGISTRY — what you
+      # can subscribe to is exactly what the gem can parse.
+      ACTIONS = Webhooks::ACTION_REGISTRY.keys.freeze
       ADDRESS_MAX_LENGTH = 500
 
       def self.create(action:, address:, platform_id: nil, prod: DEFAULT_PROD)
@@ -43,6 +41,11 @@ module DigiwinDsp
                 "action must be one of #{ACTIONS.inspect} (got #{action.inspect})"
         end
         raise DigiwinDsp::ValidationError, "address is required" if address.nil? || address.to_s.empty?
+
+        # DSPOOFFICIAL100 mandates HTTPS for the callback ("必須在 30 秒內以
+        # HTTPS 回應") — and with no HMAC signing, a plaintext callback URL
+        # would be indefensible anyway.
+        raise DigiwinDsp::ValidationError, "address must be an https:// URL (got #{address.inspect})" unless address.start_with?("https://")
         return unless address.length > ADDRESS_MAX_LENGTH
 
         raise DigiwinDsp::ValidationError,

data/lib/digiwin_dsp/version.rb

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

data/lib/digiwin_dsp/webhooks/event.rb

@@ -30,6 +30,8 @@ module DigiwinDsp
           raise(ParseError, "envelope missing digi_body.std_data.parameter.request")
       end
 
+      private_class_method :parse_json, :extract_request
+
       def initialize(digi_header:, request:, raw:)
         @digi_header = digi_header
         @request = request

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: digiwin_dsp
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Zac
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-28 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -68,6 +68,7 @@ files:
 - lib/digiwin_dsp/authenticator.rb
 - lib/digiwin_dsp/client.rb
 - lib/digiwin_dsp/configuration.rb
+- lib/digiwin_dsp/enums.rb
 - lib/digiwin_dsp/resources/base.rb
 - lib/digiwin_dsp/resources/cancellation.rb
 - lib/digiwin_dsp/resources/invoice.rb