xdelivery 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09446a0eba629a611cbe3fc4b56f751fcb5cdd34f02c30e88cd7c941cbbf6645'
-  data.tar.gz: cf34ac202d5d055b741e8db30fe3cf0b551a1ef1dd8e642e013f5c6075030d1c
+  metadata.gz: 92e95d5a3dc4d682bf321826b4386ef8b4852a17cae9a9801af04010ff89341b
+  data.tar.gz: 0ef58af566f28ef63f059b1d83b8ffb92d614d657906c4481650e51e1f8917d4
 SHA512:
-  metadata.gz: cad357967a7b44da238f6084ba67cbd1cbc3b1ae21088b7ac7a3d2c2128cb0678b4fc01385a42fcd4d4b0c569b5df07856545c5a25cf610b99fd0c530af3a2b8
-  data.tar.gz: 1ca96bc7f43b2a034666430dee8b47c78dacb4bb50eede1d225635645cc1dd42ce2c1e9f35ad4eac567d6fcf5d8724583d50b6b21eee4cc1a2199d7068f7bd11
+  metadata.gz: 9932c36d2d1ead111c920cbce76b07de96e32911e032744cfe146a3d6202b6b02942aed5e93f89767344eea44a68705cae397456ed38e1d54ada8c0d9ebdf6d7
+  data.tar.gz: 5971044b3f5277d2a9bce14d21588029777b313c2d59dfa29d30520a4ae237af89312a91c1f7d08df703c2c0ffbc8662e23dbf930d8c653c25a7ac4c127317cd

data/.github/workflows/publish.yml

@@ -0,0 +1,120 @@
+name: Publish gem
+
+# master 上 gemspec 版本號尚未發佈到 rubygems.org 時，自動以 Trusted Publishing (OIDC) 發佈。
+# 版本已存在則跳過；不使用任何儲存的 RubyGems API key。
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-gem-${{ github.repository }}
+  cancel-in-progress: false
+
+env:
+  # 與 test.yml 矩陣中最新的 Ruby 3.4.11 一致（使用根目錄 Gemfile / Gemfile.lock）
+  RUBY_VERSION: '3.4.11'
+  GEM_NAME: xdelivery
+  GEMSPEC: xdelivery-ruby.gemspec
+
+jobs:
+  check:
+    name: Check version on rubygems.org
+    runs-on: ubuntu-latest
+    outputs:
+      should_publish: ${{ steps.check.outputs.should_publish }}
+      gem_name: ${{ steps.spec.outputs.name }}
+      gem_version: ${{ steps.spec.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@b1da4809b005e0178fe08a1d57317bffc00b7b4c # v1.332.0
+        with:
+          ruby-version: ${{ env.RUBY_VERSION }}
+
+      - name: Read gem name and version from gemspec
+        id: spec
+        run: |
+          ruby -e 'spec = Gem::Specification.load(ENV.fetch("GEMSPEC")) or abort("cannot load #{ENV["GEMSPEC"]}"); abort("gemspec name #{spec.name} != #{ENV["GEM_NAME"]}") unless spec.name == ENV["GEM_NAME"]; puts "name=#{spec.name}"; puts "version=#{spec.version}"' >> "$GITHUB_OUTPUT"
+          cat "$GITHUB_OUTPUT"
+
+      - name: Check whether this version already exists on rubygems.org
+        id: check
+        env:
+          GEM_NAME: ${{ steps.spec.outputs.name }}
+          GEM_VERSION: ${{ steps.spec.outputs.version }}
+        run: |
+          set -euo pipefail
+          status=$(curl -sS -o versions.json -w '%{http_code}' "https://rubygems.org/api/v1/versions/${GEM_NAME}.json")
+          if [ "$status" = "404" ]; then
+            echo "Gem ${GEM_NAME} not found on rubygems.org; will publish."
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ "$status" != "200" ]; then
+            echo "::error::rubygems.org API returned HTTP ${status}"
+            exit 1
+          fi
+          if jq -e --arg v "$GEM_VERSION" 'any(.[]; .number == $v)' versions.json > /dev/null; then
+            echo "${GEM_NAME} ${GEM_VERSION} already on rubygems.org; skip publish."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "${GEM_NAME} ${GEM_VERSION} not on rubygems.org yet; will publish."
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  test:
+    name: Test (Ruby 3.4)
+    needs: check
+    if: needs.check.outputs.should_publish == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@b1da4809b005e0178fe08a1d57317bffc00b7b4c # v1.332.0
+        with:
+          ruby-version: ${{ env.RUBY_VERSION }}
+          bundler-cache: true
+
+      - run: bundle exec rake t
+
+  publish:
+    name: Publish ${{ needs.check.outputs.gem_name }} ${{ needs.check.outputs.gem_version }}
+    needs: [check, test]
+    if: needs.check.outputs.should_publish == 'true' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    environment: gem-publish
+    permissions:
+      id-token: write  # Trusted Publishing (OIDC)
+      contents: write  # rake release 推送 vX.Y.Z tag
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@b1da4809b005e0178fe08a1d57317bffc00b7b4c # v1.332.0
+        with:
+          ruby-version: ${{ env.RUBY_VERSION }}
+          bundler-cache: true
+
+      # setup-ruby 的 bundler-cache 會把 BUNDLE_PATH 等設定寫進 .bundle/config，
+      # 若該檔被 git 追蹤，rake release 的 guard_clean 會判定工作目錄不乾淨。
+      # 目前此 repo 沒有追蹤任何 .bundle/config；這一步對「有追蹤才標記」做容錯處理，
+      # 日後若加入 gemfiles/.bundle/config 或 .bundle/config 也不會讓發佈失敗。
+      - name: Ignore CI-only bundler config change
+        run: |
+          git status --porcelain
+          git ls-files -z '*.bundle/config' | xargs -0 -r git update-index --assume-unchanged
+          git status --porcelain
+
+      # 透過 rubygems/configure-rubygems-credentials 取得短效 OIDC token，
+      # 再執行 bundle exec rake release（build、建立並推送 vX.Y.Z tag、push gem）
+      - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1

data/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Tests
+
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.1.7", "3.3.12", "3.4.11"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake t

data/CLAUDE.md

@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+## 發版規則（Ruby gem）
+
+- 這個 gem（`xdelivery`，gemspec：`xdelivery.gemspec`）在 master 收到「新版本號」時，由 GitHub Actions（`.github/workflows/publish.yml`）自動發佈到 rubygems.org（Trusted Publishing，不使用 API key）。
+- **每一個 PR 都必須跳版號**（改 `lib/xdelivery/version.rb`），除非這個 PR 只改文件、CI 或 CLAUDE.md 且明確不需要發版。沒跳版號的 PR 合進 master 後不會發佈。
+- 跳版規則（Semantic Versioning）：修 bug 跳 patch（x.y.Z）；新增相容功能跳 minor（x.Y.0）；不相容變更跳 major（X.0.0）。
+- 版號只改在 PR 裡。AI 帳號只能開 branch 與 PR，不得合併到 master；只有真人帳號可以合併。合併就等於批准發佈。
+- 不得為了讓測試通過而改變程式原本的行為。

data/Gemfile

@@ -6,4 +6,7 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 gemspec
 
 gem 'rest-client'
-gem 'webmock'
+gem 'webmock'
+
+# public_suffix 7.x needs Ruby >= 3.2; keep 3.1 CI green
+gem 'public_suffix', '>= 2.0.2', '< 7'

data/Gemfile.lock

@@ -1,53 +1,59 @@
 PATH
   remote: .
   specs:
-    xdelivery (2.0.0)
-      rest-client
+    xdelivery (2.1.0)
+      ostruct
+      rest-client (>= 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.5.2)
-      public_suffix (>= 2.0.2, < 4.0)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
-    domain_name (0.5.20180417)
-      unf (>= 0.0.5, < 1.0.0)
-    hashdiff (0.3.7)
-    http-cookie (1.0.3)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    bigdecimal (4.1.3)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    domain_name (0.6.20260907)
+    hashdiff (1.2.1)
+    http-accept (1.7.0)
+    http-cookie (1.1.6)
       domain_name (~> 0.5)
-    mime-types (3.2.2)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2018.0812)
-    minitest (5.11.3)
+    logger (1.7.0)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2026.0922)
+    minitest (5.27.0)
     minitest-stub-const (0.6)
     netrc (0.11.0)
-    public_suffix (3.0.3)
-    rake (10.5.0)
-    rest-client (2.0.2)
+    ostruct (0.6.3)
+    public_suffix (6.0.2)
+    rake (13.4.2)
+    rest-client (2.1.0)
+      http-accept (>= 1.7.0, < 2.0)
       http-cookie (>= 1.0.2, < 2.0)
       mime-types (>= 1.16, < 4.0)
       netrc (~> 0.8)
-    safe_yaml (1.0.4)
-    unf (0.1.4)
-      unf_ext
-    unf_ext (0.0.7.5)
-    webmock (3.4.2)
-      addressable (>= 2.3.6)
+    rexml (3.4.4)
+    webmock (3.26.4)
+      addressable (>= 2.8.0)
       crack (>= 0.3.2)
-      hashdiff
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   ruby
+  x86_64-linux
 
 DEPENDENCIES
-  bundler (~> 2.3.14)
+  bundler (>= 2.3)
   minitest (~> 5.0)
   minitest-stub-const
-  rake (~> 10.0)
+  public_suffix (>= 2.0.2, < 7)
+  rake (>= 10.0)
   rest-client
   webmock
   xdelivery!
 
 BUNDLED WITH
-   2.3.14
+   2.5.23

data/Rakefile

@@ -7,4 +7,4 @@ Rake::TestTask.new(:t) do |t|
   t.test_files = FileList["spec/**/*_spec.rb"]
 end
 
-task :default => :test
+task :default => :t

data/lib/xdelivery/api/base.rb

@@ -24,20 +24,31 @@ module Xdelivery
 
       protected
 
+      # NOTICE: rescue 的順序不可以對調。
+      # RestClient 的 timeout 例外是 ExceptionWithResponse 的子孫（經由 408 RequestTimeout），
+      # 但它的 response 是 nil。若被下面那條接住並回傳 e.response，呼叫端會拿到 nil，
+      # 接著在 Response::Base 裡 nil.code 噴 NoMethodError —— 完全看不出原因是逾時。
+      # 逾時要原樣往外拋，讓呼叫端自己決定怎麼處理
       def patch(path)
         RestClient::Request.execute(method: :patch, url: uri(path).to_s, payload: patch_data, open_timeout: open_timeout, read_timeout: read_timeout)
+      rescue RestClient::Exceptions::Timeout
+        raise
       rescue RestClient::ExceptionWithResponse => e
         e.response
       end
 
       def post(path)
         RestClient::Request.execute(method: :post, url: uri(path).to_s, payload: post_data, open_timeout: open_timeout, read_timeout: read_timeout)
+      rescue RestClient::Exceptions::Timeout
+        raise
       rescue RestClient::ExceptionWithResponse => e
         e.response
       end
 
       def get(path)
         RestClient::Request.execute(method: :get, url: uri(path).to_s, open_timeout: open_timeout, read_timeout: read_timeout)
+      rescue RestClient::Exceptions::Timeout
+        raise
       rescue RestClient::ExceptionWithResponse => e
         e.response
       end
@@ -65,6 +76,16 @@ module Xdelivery
         {}
       end
 
+      # 空字串／只有空白（例如表單沒填的欄位）跟 nil 一樣視為「不掛既有紀錄」，
+      # 送出去只會讓對方拿到一個無效的 id。有值的字串則去掉前後空白才送，
+      # 不然貼上來的 " 5566 " 會被序列化成 import[history_id]=+5566+
+      def history_id_payload(history_id)
+        id = history_id.respond_to?(:strip) ? history_id.strip : history_id
+        return {} if id.to_s.empty?
+
+        { history_id: id }
+      end
+
       private
 
       def uri(path)

data/lib/xdelivery/api/orders.rb

@@ -3,7 +3,8 @@ module Xdelivery
     class Orders < Base
       include Enumerable
 
-      attr_accessor :orders
+      # history_id: 掛進火箭快遞既有匯入紀錄的 id，nil 則由對方新建一筆
+      attr_accessor :orders, :history_id
 
       COLUMNS = [
         :order_id, :provider, :recipient, :mobile, :email, :store_id, :store_name, :address,
@@ -46,7 +47,7 @@ module Xdelivery
       protected
 
       def post_data
-        { import: { orders: orders } }
+        { import: { orders: orders }.merge(history_id_payload(history_id)) }
       end
     end
   end

data/lib/xdelivery/api/response/orders.rb

@@ -16,6 +16,12 @@ module Xdelivery
         def orders
           data['orders'].map { |order| Order.new(order) }
         end
+
+        # 這批訂單被掛在哪一筆匯入紀錄底下。
+        # 失敗的回應不會帶（沒有任何訂單寫入），此時是 nil
+        def history_id
+          data['history_id']
+        end
       end
     end
   end

data/lib/xdelivery/api/sales.rb

@@ -3,7 +3,8 @@ module Xdelivery
     class Sales < Base
       include Enumerable
 
-      attr_accessor :sales
+      # history_id: 掛進火箭快遞既有匯入紀錄的 id，nil 則由對方新建一筆
+      attr_accessor :sales, :history_id
 
       COLUMNS = [
         :order_id, :recipient, :mobile, :email, :address,
@@ -46,7 +47,7 @@ module Xdelivery
       protected
 
       def post_data
-        { import: { orders: sales } }
+        { import: { orders: sales }.merge(history_id_payload(history_id)) }
       end
     end
   end

data/lib/xdelivery/client.rb

@@ -8,14 +8,18 @@ module Xdelivery
       self.access_key = access_key
     end
 
-    def create_orders!
+    # history_id 帶值時，這批訂單會掛進火箭快遞既有的匯入紀錄，
+    # 讓多次呼叫在對方後台合併成同一筆 history
+    def create_orders!(history_id: nil)
       api = API::Orders.new(merchant_no, access_key)
+      api.history_id = history_id
       yield(api)
       api.create!
     end
 
-    def create_sales!
+    def create_sales!(history_id: nil)
       api = API::Sales.new(merchant_no, access_key)
+      api.history_id = history_id
       yield(api)
       api.create!
     end

data/lib/xdelivery/version.rb

@@ -1,3 +1,3 @@
 module Xdelivery
-  VERSION = "2.0.1"
+  VERSION = "2.1.0"
 end

data/lib/xdelivery.rb

@@ -1,4 +1,5 @@
 require 'json'
+require 'ostruct'
 require 'rest-client'
 require "xdelivery/version"
 require "xdelivery/callback"
@@ -24,7 +25,7 @@ module Xdelivery
 
   @@env = :production
 
-  def self.env(env)
+  def self.env
     @@env
   end
 

data/xdelivery-ruby.gemspec

@@ -14,6 +14,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/superlanding/xdelivery-ruby"
   spec.license       = "MIT"
 
+  spec.required_ruby_version = ">= 2.7"
+
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
@@ -23,10 +25,13 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 2.3.14"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler", ">= 2.3"
+  spec.add_development_dependency "rake", ">= 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "minitest-stub-const"
   
-  spec.add_dependency "rest-client"
+  # lib/xdelivery/api/base.rb 用到 RestClient::Exceptions::Timeout，2.0 才有這個常數
+  spec.add_dependency "rest-client", ">= 2.0"
+  # OpenStruct extracted from default gems (needed on Ruby 3.3+/3.4)
+  spec.add_dependency "ostruct"
 end

metadata

@@ -1,41 +1,40 @@
 --- !ruby/object:Gem::Specification
 name: xdelivery
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - eddie
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-08-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.14
+        version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.14
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
@@ -68,6 +67,20 @@ dependencies:
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -87,8 +100,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/publish.yml"
+- ".github/workflows/test.yml"
 - ".gitignore"
 - ".travis.yml"
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -117,7 +133,6 @@ homepage: https://github.com/superlanding/xdelivery-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -125,15 +140,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: 火箭快遞 API 串接
 test_files: []