NewebPay Logistics Node.js SDK

用於整合藍新金流物流 API 的 Node.js SDK。

功能特色

• ✅ TypeScript 完整支援
• ✅ Node.js 18+ 支援（使用原生 fetch 和 node:crypto）
• ✅ Zod 資料驗證
• ✅ 完整的型別定義
• ✅ 測試/正式環境切換
• ✅ 完善的錯誤處理
• ✅ XSS 防護（FormBuilder）
• ✅ 加密金鑰長度驗證

安裝

npm install @carllee1983/newebpay-logistics

使用方式

初始化

import { NewebPayLogistics, Environment } from '@carllee1983/newebpay-logistics';

// 測試環境（預設）
const logistics = new NewebPayLogistics(
  'YOUR_MERCHANT_ID',
  'YOUR_HASH_KEY',
  'YOUR_HASH_IV'
);

// 正式環境
const logisticsProd = new NewebPayLogistics(
  'YOUR_MERCHANT_ID',
  'YOUR_HASH_KEY',
  'YOUR_HASH_IV',
  undefined, // 可選的自訂 HttpClient
  Environment.PRODUCTION
);

Map 介面（物流選擇）

import { LgsType, ShipType, FormBuilder } from '@carllee1983/newebpay-logistics';

const map = logistics.map();
map.setMerchantTradeNo('TRADE' + Date.now())
   .setLgsType(LgsType.B2C)
   .setShipType(ShipType.SEVEN_ELEVEN)
   .setReturnURL('https://example.com/return')
   .setTimeStamp(Math.floor(Date.now() / 1000))
   .setIsCollection('Y')
   .setServerReplyURL('https://example.com/callback');

// 產生 HTML 表單
const formBuilder = new FormBuilder();
const html = formBuilder.build(map);
console.log(html);

建立訂單

import { LgsType, ShipType, TradeType } from '@carllee1983/newebpay-logistics';

const create = logistics.createOrder();
create.setMerchantTradeNo('TRADE' + Date.now())
      .setLgsType(LgsType.B2C)
      .setShipType(ShipType.SEVEN_ELEVEN)
      .setTradeType(TradeType.PAYMENT)
      .setAmt(100)
      .setUserName('測試使用者')
      .setUserEmail('[email protected]')
      .setReceiverName('收件者')
      .setReceiverEmail('[email protected]')
      .setTimeStamp(Math.floor(Date.now() / 1000));

try {
  const response = await logistics.send(create);
  if (response.isSuccess()) {
    console.log('訂單建立成功:', response.getData());
  } else {
    console.error('訂單建立失敗:', response.getMessage());
  }
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('驗證錯誤:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('網路錯誤:', error.message);
  } else if (error instanceof ApiError) {
    console.error('API 錯誤:', error.message, error.status);
  }
}

查詢訂單

const query = logistics.queryOrder();
query.setMerchantTradeNo('TRADE123456')
     .setTimeStamp(Math.floor(Date.now() / 1000))
     .setLogisticsID('LOGISTICS_ID'); // 可選

try {
  const response = await logistics.send(query);
  console.log('訂單狀態:', response.getData());
} catch (error) {
  console.error('查詢失敗:', error);
}

列印訂單

const print = logistics.printOrder();
print.setMerchantTradeNo('TRADE123456')
     .setTimeStamp(Math.floor(Date.now() / 1000))
     .setLogisticsID('LOGISTICS_ID'); // 可選

try {
  const response = await logistics.send(print);
  if (response instanceof PrintOrderResponse) {
    const html = response.getHtmlContent();
    console.log('列印 HTML:', html);
  }
} catch (error) {
  console.error('列印失敗:', error);
}

錯誤處理

SDK 提供多種錯誤類型，方便進行錯誤處理：

import { 
  NewebPayError, 
  NetworkError, 
  ApiError, 
  ValidationError 
} from '@carllee1983/newebpay-logistics';

try {
  const response = await logistics.send(request);
} catch (error) {
  if (error instanceof ValidationError) {
    // 請求驗證失敗（例如：必填欄位缺失、格式錯誤等）
    console.error('驗證錯誤:', error.message);
  } else if (error instanceof NetworkError) {
    // 網路請求失敗
    console.error('網路錯誤:', error.message);
    console.error('原始錯誤:', error.originalError);
  } else if (error instanceof ApiError) {
    // API 回傳錯誤
    console.error('API 錯誤:', error.message);
    console.error('狀態碼:', error.status);
    console.error('錯誤資料:', error.data);
  } else if (error instanceof NewebPayError) {
    // 其他 NewebPay 相關錯誤
    console.error('其他錯誤:', error.message);
  }
}

API 參考

NewebPayLogistics

主要的 SDK 客戶端類別。

建構子

constructor(
  merchantId: string,
  hashKey: string,
  hashIV: string,
  httpClient?: HttpClient,
  environment?: Environment
)

方法

• map(): 建立 MapRequest 實例
• createOrder(): 建立 CreateOrderRequest 實例
• queryOrder(): 建立 QueryOrderRequest 實例
• printOrder(): 建立 PrintOrderRequest 實例
• send(request: BaseRequest): Promise<BaseResponse>: 發送請求

常數

LgsType（物流類型）

• LgsType.B2C: 企業對消費者
• LgsType.C2C: 消費者對消費者

ShipType（配送類型）

• ShipType.SEVEN_ELEVEN: 7-Eleven
• ShipType.FAMILY: FamilyMart
• ShipType.HILIFE: Hi-Life
• ShipType.OK: OK Mart

TradeType（交易類型）

• TradeType.PAYMENT: 需要付款
• TradeType.NON_PAYMENT: 不需要付款

Environment（環境）

• Environment.TEST: 測試環境（預設）
• Environment.PRODUCTION: 正式環境

開發

前置需求

• Node.js 18 或更高版本

設定

npm install

測試

執行單元測試：

npm test

監聽模式執行測試：

npm run test:watch

建置

建置專案：

npm run build

程式碼檢查與格式化

檢查程式碼錯誤：

npm run lint

格式化程式碼：

npm run format

注意事項

1. 加密金鑰長度：hashKey 必須為 32 bytes，hashIV 必須為 16 bytes。SDK 會自動驗證長度，不符合時會拋出 ValidationError。

2. 環境切換：預設使用測試環境，正式環境請明確指定 Environment.PRODUCTION。

3. 錯誤處理：建議使用 try-catch 並檢查錯誤類型，以便進行適當的錯誤處理。

4. FormBuilder 安全性：FormBuilder 會自動對 HTML 屬性值進行轉義，防止 XSS 攻擊。

授權

MIT