# @whitehole/open-api-sdk

白洞门店云开放接口 Node.js 服务端 SDK，封装请求签名、分页参数、错误码和当前已开放的只读资源方法。

## 安装方式

当前官网提供静态包资产。发布到私有 npm 仓库前，请把下列文件放入同一个发布目录，并将 `whitehole-open-api-sdk.package.json` 重命名为 `package.json`：

- `whitehole-open-api-sdk.js`
- `whitehole-open-api-sdk.d.ts`
- `whitehole-open-api-sdk.README.md`
- `whitehole-open-api-sdk.CHANGELOG.md`
- `whitehole-open-api-sdk.RELEASE.md`

发布前执行：

```bash
node whitehole-open-api-sdk.verify.js
npm pack --dry-run
```

## 服务端示例

```js
const { WhiteholeOpenApiClient } = require('@whitehole/open-api-sdk');

const client = new WhiteholeOpenApiClient({
  baseUrl: process.env.WH_OPEN_API_BASE_URL || 'https://open.whbdvr.com',
  appKey: process.env.WH_OPEN_API_APP_KEY,
  appSecret: process.env.WH_OPEN_API_APP_SECRET,
  retry: 2,
});

async function main() {
  const overview = await client.getBusinessOverview({
    startDate: '2026-05-01',
    endDate: '2026-05-07',
  });
  console.log(overview);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

不要在浏览器里放入 appSecret。开放接口凭证只适合保存在外部系统服务端，前端页面或移动端页面不能直接持有密钥。

## 常用导出

- `SDK_VERSION`
- `OPEN_API_ERROR_CODES`
- `WhiteholeOpenApiClient`
- `buildPageQuery`
- `signOpenApiRequest`
- `requestOpenApi`

## 资源方法

- `getTenantProfile()`
- `listProducts(query)`
- `listStockRecords(query)`
- `listMembers(query)`
- `listMemberConsumes(query)`
- `listOrders(query)`
- `getOrderDetail(orderNo)`
- `getBusinessOverview(query)`
- `getBusinessTrend(query)`
- `getProductSalesRanking(query)`
- `getMemberGrowthRetention(query)`
- `getBusinessMetricGroups(query)`