{"_id":"@be-link/express-delivery-api-sdk","name":"@be-link/express-delivery-api-sdk","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.4":{"name":"@be-link/express-delivery-api-sdk","version":"0.0.4","description":"https://api.kuaidi100.com/document","main":"index.js","repository":{"type":"git","url":"git+https://github.com/snowmountain-top/express-delivery.git"},"keywords":["volcengine","sdk","node","typescript"],"author":{"name":"dev@8848top.com"},"license":"ISC","dependencies":{"axios":"^1.7.0","husky":"^8.0.3"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"devDependencies":{"@types/jest":"^30.0.0","@types/node":"^22.7.4","jest":"^30.2.0","ts-jest":"^29.4.6","typescript":"^5.6.0"},"scripts":{"build":"rm -rf ./dist && tsc && cp package.json README.md ./dist/","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","update:major":"standard-version --release-as major","update:minor":"standard-version  --release-as minor","update:patch":"standard-version  --release-as patch","update:beta":"standard-version --prerelease beta"},"_id":"@be-link/express-delivery-api-sdk@0.0.4","types":"./index.d.ts","bugs":{"url":"https://github.com/snowmountain-top/express-delivery/issues"},"homepage":"https://github.com/snowmountain-top/express-delivery#readme","_integrity":"sha512-kJlm0CVaa+DV+35Z7iHmG/+IOyxuWvkjHzu6sfVrtMGalhzeiWhwnUYy1Bonlf0Usiizw7dzD3jdvKsXDENfvA==","_resolved":"/tmp/2c82d0f36f4713b390a912b5e3d85df1/be-link-express-delivery-api-sdk-0.0.4.tgz","_from":"file:be-link-express-delivery-api-sdk-0.0.4.tgz","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-kJlm0CVaa+DV+35Z7iHmG/+IOyxuWvkjHzu6sfVrtMGalhzeiWhwnUYy1Bonlf0Usiizw7dzD3jdvKsXDENfvA==","shasum":"b153ae9dc9c06eb5403b784bff8d19020ad64344","tarball":"https://registry.npmjs.org/@be-link/express-delivery-api-sdk/-/express-delivery-api-sdk-0.0.4.tgz","fileCount":16,"unpackedSize":51148,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCehL0009DqscByw9F2NAw6VfRLs/320EUKWch5EeQmbAIhAJa7zqakuduk634Qv5dJyWZUkFw0YU89XnnL9zJULhDG"}]},"_npmUser":{"name":"8848top-dev","email":"dev@8848top.com"},"directories":{},"maintainers":[{"name":"8848top-dev","email":"dev@8848top.com"},{"name":"hanguodong","email":"875521275@qq.com"},{"name":"wangml0310","email":"2576306481@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/express-delivery-api-sdk_0.0.4_1770207429177_0.09795340964009247"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-04T12:17:09.114Z","0.0.4":"2026-02-04T12:17:09.314Z","modified":"2026-02-04T12:17:09.525Z"},"maintainers":[{"name":"8848top-dev","email":"dev@8848top.com"},{"name":"hanguodong","email":"875521275@qq.com"},{"name":"wangml0310","email":"2576306481@qq.com"}],"description":"https://api.kuaidi100.com/document","homepage":"https://github.com/snowmountain-top/express-delivery#readme","keywords":["volcengine","sdk","node","typescript"],"repository":{"type":"git","url":"git+https://github.com/snowmountain-top/express-delivery.git"},"author":{"name":"dev@8848top.com"},"bugs":{"url":"https://github.com/snowmountain-top/express-delivery/issues"},"license":"ISC","readme":"# Express Delivery API SDK\n\n快递100 API 的 TypeScript SDK，提供完整的类型定义和便捷的接口封装。\n\n## 功能特性\n\n-  **实时快递查询** - 查询快递单号的实时物流轨迹\n-  **地图轨迹查询** - 获取带地图轨迹的物流信息\n-  **快递订阅** - 订阅快递单号，接收物流状态推送\n-  **Webhook 支持** - 解析和验证快递100推送的回调数据\n-  **自动限流** - 内置固定窗口限流器，防止请求过载\n-  **自动重试** - 支持可配置的重试机制\n-  **完整类型** - 全面的 TypeScript 类型定义，提供良好的开发体验\n\n## 安装\n\n```bash\nnpm install @be-link/express-delivery-api-sdk\n# 或\npnpm add @be-link/express-delivery-api-sdk\n# 或\nyarn add @be-link/express-delivery-api-sdk\n```\n\n## 快速开始\n\n### 初始化客户端\n\n```typescript\nimport { ExpressDeliveryClient } from '@be-link/express-delivery-api-sdk';\n\nconst client = new ExpressDeliveryClient({\n  customer: 'YOUR_CUSTOMER_ID',  // 快递100 企业编号\n  key: 'YOUR_API_KEY',           // 授权 key\n  baseURL: 'https://poll.kuaidi100.com', // 可选，默认值\n  timeoutMs: 5000,               // 可选，默认 5000ms\n});\n```\n\n### 实时快递查询\n\n```typescript\nimport { ExpressDeliveryClient } from '@be-link/express-delivery-api-sdk';\n\nconst client = new ExpressDeliveryClient({\n  customer: 'YOUR_CUSTOMER_ID',\n  key: 'YOUR_API_KEY',\n});\n\nconst result = await client.realTimeQuery({\n  com: 'yuantong',              // 快递公司编码\n  num: 'YT25569986666541',      // 快递单号\n  phone: '13800138000',         // 可选，收寄件人电话\n  from: '安徽省六安市霍邱县',    // 可选，出发地\n  to: '江苏省苏州市昆山市',      // 可选，目的地\n  resultv2: 1,                  // 可选，返回详细结果\n  order: 'desc',                // 可选，排序方式\n});\n\nif (result.ok) {\n  console.log('快递状态:', result.data?.state);\n  console.log('轨迹信息:', result.data?.data);\n} else {\n  console.error('查询失败:', result.infoMessage);\n}\n```\n\n### 地图轨迹查询\n\n```typescript\nconst result = await client.mapTrackQuery({\n  com: 'yuantong',\n  num: 'YT25569986666541',\n  from: '广东省深圳市南山区',\n  to: '江苏省南京市玄武区',\n  resultv2: '7',                // 可选，返回 AI 时效预测\n  needCourierInfo: true,        // 可选，返回快递员信息\n});\n\nif (result.ok) {\n  console.log('地图轨迹链接:', result.data?.trailUrl);\n  console.log('快递员信息:', result.data?.courierInfo);\n}\n```\n\n### 快递订阅\n\n```typescript\nconst result = await client.subscribeTracking({\n  company: 'yuantong',\n  number: 'YT6186594166532',\n  from: '广东省深圳市南山区',\n  to: '江苏省南京市玄武区',\n  parameters: {\n    callbackUrl: 'https://your-domain.com/webhook/kuaidi',\n    salt: 'YOUR_SALT',          // 可选，用于签名验证\n    resultv2: '4',              // 可选，返回详细结果\n    autoCom: '0',               // 可选，是否开启智能识别\n  },\n});\n\nif (result.ok) {\n  console.log('订阅成功');\n}\n```\n\n### Webhook 回调处理\n\n```typescript\nimport {\n  parseExpressDeliveryPush,\n  verifyExpressDeliveryPushSignature,\n} from '@be-link/express-delivery-api-sdk';\n\n// Express 示例\napp.post('/webhook/kuaidi', express.urlencoded({ extended: true }), (req, res) => {\n  try {\n    // 解析推送数据\n    const { request, payload } = parseExpressDeliveryPush(req.body);\n    \n    // 验证签名（如果订阅时提供了 salt）\n    const salt = 'YOUR_SALT'; // 从数据库或其他地方获取\n    if (!verifyExpressDeliveryPushSignature(request.param, salt, request.sign)) {\n      return res.status(401).send('Invalid signature');\n    }\n    \n    // 处理推送数据\n    console.log('任务状态:', payload.status);\n    console.log('运单状态:', payload.billstatus);\n    console.log('最新轨迹:', payload.lastResult);\n    \n    res.status(200).send('ok');\n  } catch (error) {\n    console.error('处理推送失败:', error);\n    res.status(500).send('Internal error');\n  }\n});\n```\n\n## 高级配置\n\n### 自定义限流器\n\n```typescript\nimport { ExpressDeliveryClient, FixedWindowRateLimiter } from '@be-link/express-delivery-api-sdk';\n\nconst client = new ExpressDeliveryClient({\n  customer: 'YOUR_CUSTOMER_ID',\n  key: 'YOUR_API_KEY',\n  rateLimiter: new FixedWindowRateLimiter({\n    maxRequests: 20,    // 每个窗口最大请求数\n    windowMs: 1000,     // 时间窗口（毫秒）\n  }),\n});\n```\n\n### 自定义重试配置\n\n```typescript\nconst client = new ExpressDeliveryClient({\n  customer: 'YOUR_CUSTOMER_ID',\n  key: 'YOUR_API_KEY',\n  retry: {\n    maxRetries: 5,      // 最大重试次数\n    baseDelayMs: 1000,  // 基础延迟时间（毫秒）\n  },\n});\n```\n\n### 通用请求方法\n\n```typescript\n// 使用通用 request 方法调用其他 API\nconst result = await client.request({\n  path: '/custom/endpoint',\n  method: 'POST',\n  payload: { /* 你的参数 */ },\n  contentType: 'form',  // 或 'json'\n  needSign: true,       // 是否需要签名\n});\n```\n\n## API 参考\n\n### ExpressDeliveryClient\n\n#### 构造函数选项\n\n- `customer` (string, 必需) - 快递100 企业编号\n- `key` (string, 必需) - 授权 key\n- `baseURL` (string, 可选) - API 根地址，默认 `https://poll.kuaidi100.com`\n- `timeoutMs` (number, 可选) - 请求超时时间，默认 `5000`\n- `rateLimiter` (RateLimiter, 可选) - 自定义限流器\n- `retry` (Partial<RetryOptions>, 可选) - 重试配置\n\n#### 方法\n\n- `realTimeQuery(payload: RealTimeQueryPayload)` - 实时快递查询\n- `mapTrackQuery(payload: MapTrackQueryPayload)` - 地图轨迹查询\n- `subscribeTracking(payload: SubscribeTrackingPayload)` - 快递订阅\n- `request<TPayload, TData>(options: ExpressDeliveryRequestOptions)` - 通用请求方法\n\n### 枚举类型\n\n- `ExpressDeliveryInfoCode` - API 响应状态码\n- `ExpressDeliveryShipmentState` - 物流状态\n- `ExpressDeliveryPushTaskStatus` - 推送任务状态\n- `ExpressDeliveryBillStatus` - 运单业务状态\n\n### Webhook 工具\n\n- `parseExpressDeliveryPush(body)` - 解析推送数据\n- `verifyExpressDeliveryPushSignature(param, salt, sign)` - 验证签名\n\n## 开发\n\n```bash\n# 安装依赖\npnpm install\n\n# 运行测试\npnpm test\n\n# 监听模式运行测试\npnpm test:watch\n\n# 生成测试覆盖率报告\npnpm test:coverage\n\n# 构建项目\npnpm build\n```\n\n## 相关文档\n\n- [快递100 API 文档](https://api.kuaidi100.com/document)\n\n## 作者\n\ndev@8848top.com\n","readmeFilename":"README.md","_rev":"1-b0cb8088d807145c9633e1ed427ca9fb"}