{"_id":"@carllee1983/newebpay-logistics","_rev":"4-bd50f5dd305816f5ebf675d0c602d6f5","name":"@carllee1983/newebpay-logistics","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@carllee1983/newebpay-logistics","version":"1.0.0","keywords":["newebpay","logistics","node","typescript","sdk"],"author":{"name":"Carl Lee"},"license":"MIT","_id":"@carllee1983/newebpay-logistics@1.0.0","maintainers":[{"name":"carllee1983","email":"carllee0520@gmail.com"}],"dist":{"shasum":"9d5f0ca6373f5ebb0706273e096a1b6845145f29","tarball":"https://registry.npmjs.org/@carllee1983/newebpay-logistics/-/newebpay-logistics-1.0.0.tgz","fileCount":77,"integrity":"sha512-rt1DZ2J0MOgmh9Oypoamf+x3AcDQw2Hh2BwKVawUXRUpzp+zeYBsojkH+PdtHw125wXwerNBJODTDLeGp9dGAg==","signatures":[{"sig":"MEUCIQCuP48eu2Am74yVF6z/KpdSzXFM0lzSCDp+XcWpdmMWgQIgcZob40xkr+EBpbJi8oWKYek5Wg/41rAAENTwqKZJLhA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84616},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":"./dist/index.js"},"gitHead":"8bf664321979cc9203c3b647ca3ef2d47c9c4b77","scripts":{"lint":"eslint src/**/*.ts","test":"vitest run","build":"tsc","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"carllee1983","email":"carllee0520@gmail.com"},"_npmVersion":"10.8.2","description":"藍新金流物流 SDK - NewebPay Logistics SDK for Node.js","directories":{},"_nodeVersion":"18.20.8","dependencies":{"zod":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.0.0","vitest":"^1.0.0","prettier":"^3.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/newebpay-logistics_1.0.0_1764423582799_0.01818854694381633","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@carllee1983/newebpay-logistics","version":"1.0.1","keywords":["newebpay","logistics","node","typescript","sdk"],"author":{"name":"Carl Lee"},"license":"MIT","_id":"@carllee1983/newebpay-logistics@1.0.1","maintainers":[{"name":"carllee1983","email":"carllee0520@gmail.com"}],"dist":{"shasum":"bb34f95e5a7fa8641be9b070dc7cc8b98a157f36","tarball":"https://registry.npmjs.org/@carllee1983/newebpay-logistics/-/newebpay-logistics-1.0.1.tgz","fileCount":77,"integrity":"sha512-pXGY6WH1x3hpLe2Xs/SjfSwV4EHMX3fwm3sl2EoPqN7Dlz9W+1VMV3J0mlfN30w6JKUuWryx/FIrUMs8aOemgg==","signatures":[{"sig":"MEQCIG8eS3TriaPgnZP8jGFJejYQTci8H2jhhUQht7dOZYi/AiBdwldzlQiKea+WphINZXe37QP5LGgB2P/l0WFOunmQ2w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":118968},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":"./dist/index.js"},"gitHead":"4013d33b94452f6afb211ee863bb265e79dd7fcb","scripts":{"lint":"eslint src/**/*.ts","test":"vitest run","build":"tsc","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"carllee1983","email":"carllee0520@gmail.com"},"_npmVersion":"10.8.2","description":"藍新金流物流 SDK - NewebPay Logistics SDK for Node.js","directories":{},"_nodeVersion":"18.20.8","dependencies":{"zod":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.0.0","vitest":"^1.0.0","prettier":"^3.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/newebpay-logistics_1.0.1_1764424496239_0.9047111305581088","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@carllee1983/newebpay-logistics","version":"1.0.2","keywords":["newebpay","藍新金流","logistics","物流","shipping","delivery","cvs","convenience-store","7-11","7eleven","familymart","hilife","okmart","node","nodejs","typescript","sdk","api","integration","payment","ecommerce","taiwan","台灣"],"author":{"name":"Carl Lee"},"license":"MIT","_id":"@carllee1983/newebpay-logistics@1.0.2","maintainers":[{"name":"carllee1983","email":"carllee0520@gmail.com"}],"dist":{"shasum":"f286eac4c094454baddd0e64abcf5219aa8a5b08","tarball":"https://registry.npmjs.org/@carllee1983/newebpay-logistics/-/newebpay-logistics-1.0.2.tgz","fileCount":56,"integrity":"sha512-BVOJvsTG0LPc+IlDXR4225sM86me8tW4UnR7aBPlZyW068eVpAeOeVeurDn8UUx1ggLTQOSsZAt44+SG2HXSDw==","signatures":[{"sig":"MEUCIHMtpQ+NQD6XFIvRJI8EuSuXuP4KNAyRZXIOhAQoM7m/AiEAnabXNAYJB67cyMnqv+CYBY9MF08TQ/V9q2UnkB1e4ZQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":96129},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"abb1c4f61e3436ee4609735db8c30290bc4847af","scripts":{"lint":"eslint 'src/**/*.ts'","test":"vitest run","build":"tsc","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","test:ui":"vitest --ui","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"carllee1983","email":"carllee0520@gmail.com"},"_npmVersion":"10.8.2","description":"藍新金流物流 SDK - 完整的 TypeScript 支援、資料驗證、錯誤處理與 XSS 防護的 NewebPay Logistics API 整合套件","directories":{},"_nodeVersion":"20.18.1","dependencies":{"zod":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.0.0","vitest":"^1.0.0","prettier":"^3.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@vitest/coverage-v8":"^1.6.1","@typescript-eslint/parser":"^8.49.0","@typescript-eslint/eslint-plugin":"^8.49.0"},"_npmOperationalInternal":{"tmp":"tmp/newebpay-logistics_1.0.2_1765523998888_0.8247732167432036","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-11-29T13:39:42.724Z","modified":"2026-09-15T02:54:45.021Z","1.0.0":"2025-11-29T13:39:43.000Z","1.0.1":"2025-11-29T13:54:56.417Z","1.0.2":"2025-12-12T07:19:59.021Z"},"author":{"name":"Carl Lee"},"license":"MIT","keywords":["newebpay","藍新金流","logistics","物流","shipping","delivery","cvs","convenience-store","7-11","7eleven","familymart","hilife","okmart","node","nodejs","typescript","sdk","api","integration","payment","ecommerce","taiwan","台灣"],"description":"藍新金流物流 SDK - 完整的 TypeScript 支援、資料驗證、錯誤處理與 XSS 防護的 NewebPay Logistics API 整合套件","maintainers":[{"email":"yashino538@gmail.com","name":"praxisbound"}],"readme":"# NewebPay Logistics Node.js SDK\n\n用於整合藍新金流物流 API 的 Node.js SDK。\n\n## 功能特色\n\n- ✅ TypeScript 完整支援\n- ✅ Node.js 18+ 支援（使用原生 `fetch` 和 `node:crypto`）\n- ✅ Zod 資料驗證\n- ✅ 完整的型別定義\n- ✅ 測試/正式環境切換\n- ✅ 完善的錯誤處理\n- ✅ XSS 防護（FormBuilder）\n- ✅ 加密金鑰長度驗證\n\n## 安裝\n\n```bash\nnpm install @carllee1983/newebpay-logistics\n```\n\n## 使用方式\n\n### 初始化\n\n```typescript\nimport { NewebPayLogistics, Environment } from '@carllee1983/newebpay-logistics';\n\n// 測試環境（預設）\nconst logistics = new NewebPayLogistics(\n  'YOUR_MERCHANT_ID',\n  'YOUR_HASH_KEY',\n  'YOUR_HASH_IV'\n);\n\n// 正式環境\nconst logisticsProd = new NewebPayLogistics(\n  'YOUR_MERCHANT_ID',\n  'YOUR_HASH_KEY',\n  'YOUR_HASH_IV',\n  undefined, // 可選的自訂 HttpClient\n  Environment.PRODUCTION\n);\n```\n\n### Map 介面（物流選擇）\n\n```typescript\nimport { LgsType, ShipType, FormBuilder } from '@carllee1983/newebpay-logistics';\n\nconst map = logistics.map();\nmap.setMerchantTradeNo('TRADE' + Date.now())\n   .setLgsType(LgsType.B2C)\n   .setShipType(ShipType.SEVEN_ELEVEN)\n   .setReturnURL('https://example.com/return')\n   .setTimeStamp(Math.floor(Date.now() / 1000))\n   .setIsCollection('Y')\n   .setServerReplyURL('https://example.com/callback');\n\n// 產生 HTML 表單\nconst formBuilder = new FormBuilder();\nconst html = formBuilder.build(map);\nconsole.log(html);\n```\n\n### 建立訂單\n\n```typescript\nimport { LgsType, ShipType, TradeType } from '@carllee1983/newebpay-logistics';\n\nconst create = logistics.createOrder();\ncreate.setMerchantTradeNo('TRADE' + Date.now())\n      .setLgsType(LgsType.B2C)\n      .setShipType(ShipType.SEVEN_ELEVEN)\n      .setTradeType(TradeType.PAYMENT)\n      .setAmt(100)\n      .setUserName('測試使用者')\n      .setUserEmail('user@example.com')\n      .setReceiverName('收件者')\n      .setReceiverEmail('receiver@example.com')\n      .setTimeStamp(Math.floor(Date.now() / 1000));\n\ntry {\n  const response = await logistics.send(create);\n  if (response.isSuccess()) {\n    console.log('訂單建立成功:', response.getData());\n  } else {\n    console.error('訂單建立失敗:', response.getMessage());\n  }\n} catch (error) {\n  if (error instanceof ValidationError) {\n    console.error('驗證錯誤:', error.message);\n  } else if (error instanceof NetworkError) {\n    console.error('網路錯誤:', error.message);\n  } else if (error instanceof ApiError) {\n    console.error('API 錯誤:', error.message, error.status);\n  }\n}\n```\n\n### 查詢訂單\n\n```typescript\nconst query = logistics.queryOrder();\nquery.setMerchantTradeNo('TRADE123456')\n     .setTimeStamp(Math.floor(Date.now() / 1000))\n     .setLogisticsID('LOGISTICS_ID'); // 可選\n\ntry {\n  const response = await logistics.send(query);\n  console.log('訂單狀態:', response.getData());\n} catch (error) {\n  console.error('查詢失敗:', error);\n}\n```\n\n### 列印訂單\n\n```typescript\nconst print = logistics.printOrder();\nprint.setMerchantTradeNo('TRADE123456')\n     .setTimeStamp(Math.floor(Date.now() / 1000))\n     .setLogisticsID('LOGISTICS_ID'); // 可選\n\ntry {\n  const response = await logistics.send(print);\n  if (response instanceof PrintOrderResponse) {\n    const html = response.getHtmlContent();\n    console.log('列印 HTML:', html);\n  }\n} catch (error) {\n  console.error('列印失敗:', error);\n}\n```\n\n## 錯誤處理\n\nSDK 提供多種錯誤類型，方便進行錯誤處理：\n\n```typescript\nimport { \n  NewebPayError, \n  NetworkError, \n  ApiError, \n  ValidationError \n} from '@carllee1983/newebpay-logistics';\n\ntry {\n  const response = await logistics.send(request);\n} catch (error) {\n  if (error instanceof ValidationError) {\n    // 請求驗證失敗（例如：必填欄位缺失、格式錯誤等）\n    console.error('驗證錯誤:', error.message);\n  } else if (error instanceof NetworkError) {\n    // 網路請求失敗\n    console.error('網路錯誤:', error.message);\n    console.error('原始錯誤:', error.originalError);\n  } else if (error instanceof ApiError) {\n    // API 回傳錯誤\n    console.error('API 錯誤:', error.message);\n    console.error('狀態碼:', error.status);\n    console.error('錯誤資料:', error.data);\n  } else if (error instanceof NewebPayError) {\n    // 其他 NewebPay 相關錯誤\n    console.error('其他錯誤:', error.message);\n  }\n}\n```\n\n## API 參考\n\n### NewebPayLogistics\n\n主要的 SDK 客戶端類別。\n\n#### 建構子\n\n```typescript\nconstructor(\n  merchantId: string,\n  hashKey: string,\n  hashIV: string,\n  httpClient?: HttpClient,\n  environment?: Environment\n)\n```\n\n#### 方法\n\n- `map()`: 建立 MapRequest 實例\n- `createOrder()`: 建立 CreateOrderRequest 實例\n- `queryOrder()`: 建立 QueryOrderRequest 實例\n- `printOrder()`: 建立 PrintOrderRequest 實例\n- `send(request: BaseRequest): Promise<BaseResponse>`: 發送請求\n\n### 常數\n\n#### LgsType（物流類型）\n\n- `LgsType.B2C`: 企業對消費者\n- `LgsType.C2C`: 消費者對消費者\n\n#### ShipType（配送類型）\n\n- `ShipType.SEVEN_ELEVEN`: 7-Eleven\n- `ShipType.FAMILY`: FamilyMart\n- `ShipType.HILIFE`: Hi-Life\n- `ShipType.OK`: OK Mart\n\n#### TradeType（交易類型）\n\n- `TradeType.PAYMENT`: 需要付款\n- `TradeType.NON_PAYMENT`: 不需要付款\n\n#### Environment（環境）\n\n- `Environment.TEST`: 測試環境（預設）\n- `Environment.PRODUCTION`: 正式環境\n\n## 開發\n\n### 前置需求\n\n- Node.js 18 或更高版本\n\n### 設定\n\n```bash\nnpm install\n```\n\n### 測試\n\n執行單元測試：\n\n```bash\nnpm test\n```\n\n監聽模式執行測試：\n\n```bash\nnpm run test:watch\n```\n\n### 建置\n\n建置專案：\n\n```bash\nnpm run build\n```\n\n### 程式碼檢查與格式化\n\n檢查程式碼錯誤：\n\n```bash\nnpm run lint\n```\n\n格式化程式碼：\n\n```bash\nnpm run format\n```\n\n## 注意事項\n\n1. **加密金鑰長度**：`hashKey` 必須為 32 bytes，`hashIV` 必須為 16 bytes。SDK 會自動驗證長度，不符合時會拋出 `ValidationError`。\n\n2. **環境切換**：預設使用測試環境，正式環境請明確指定 `Environment.PRODUCTION`。\n\n3. **錯誤處理**：建議使用 try-catch 並檢查錯誤類型，以便進行適當的錯誤處理。\n\n4. **FormBuilder 安全性**：FormBuilder 會自動對 HTML 屬性值進行轉義，防止 XSS 攻擊。\n\n## 授權\n\nMIT\n","readmeFilename":"README.md"}