digiwin_dsp 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cfde42cbd2b4448e9c5e4927e9ecb65f61ae19a46474154ae1349d73cd2461c
-  data.tar.gz: 6d35ad2fd9430c5440f626b15f3c98c9a8dd627c2732bb349bc355f6693d9de3
+  metadata.gz: 8b74fbc1739d80f99a563f002be9ab06212eb0ffce531ddf9144c9c8ceb28b34
+  data.tar.gz: 363e1faecee60d9a4c8f5cfe03b00bf2febd35f015f0034451e1c9c9e191308a
 SHA512:
-  metadata.gz: 95d2787c766fa0a316542b37d0b5620738e9dcff687562875698e5c1d0f3a3ffaaa2e93a81f24b34e0f6e27047a9c53d22e1368725879f36a6f48116b02f2b7c
-  data.tar.gz: c8f1b7781c06e3fa745d4e2a6770d7442dd443a38e10ca4ce6767b5aaa82bbf1016ef8aeb961922ebe9f41321d6702be561a1c82810223335a0a340c6f6eb27b
+  metadata.gz: b14060dbe2c6d65890ffb925c1ee9f499a7870db0c4eb301646eaf0ea2907869e0e331d8ff14b76e1a6bd474a2de5bf75f97d9bdf5073d856a5c55b6753dd225
+  data.tar.gz: 1f1f7ab22cd0e077e455ce7cc6451442e5285ccf7e1c94a1abcb0c6e284e3fc86f94cf879170b4ddd2cc3d747ca532ba64a6082bf89be972aacadef23df33e7c

data/CHANGELOG.md

@@ -6,6 +6,31 @@ 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.
@@ -226,7 +251,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.3.1...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

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:
@@ -219,6 +220,20 @@ end
 > - 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

@@ -132,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)

data/lib/digiwin_dsp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: digiwin_dsp
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Zac
@@ -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