UniRate-API/payload-plugin-unirate
GitHub: UniRate-API/payload-plugin-unirate
Payload CMS v3 插件，通过服务端代理接入 UniRate 汇率 API，为应用提供汇率查询、金额转换、货币列表和 VAT 税率功能。
Stars: 0 | Forks: 0
# payload-plugin-unirate
一个集成了 [UniRate API](https://unirateapi.com)（用于货币汇率和 VAT 数据）的 [Payload CMS](https://payloadcms.com) **v3** 插件。
它会在 `/api/unirate` 下追加四个服务端 endpoint，并提供了一个可选的预填充货币 `select` 字段——你的 API key 仅保留在服务端，绝不会暴露给客户端。**零运行时依赖**（`payload` 为 peer dependency）。
## 安装
```
npm install payload-plugin-unirate
```
要求 Payload `>=3.0.0`（peer dependency）以及 Node `>=18.20`。
## 快速开始
```
// payload.config.ts
import { buildConfig } from "payload";
import { uniratePlugin } from "payload-plugin-unirate";
export default buildConfig({
// ...your usual config
plugins: [
uniratePlugin({
apiKey: process.env.UNIRATE_API_KEY, // or omit and set the env var
}),
],
});
```
设置你的 key（推荐方式，优于直接内联）：
```
UNIRATE_API_KEY=your_key_here
```
## 选项
`uniratePlugin(options)`：
| 选项 | 类型 | 默认值 | 描述 |
|--------|------|---------|-------------|
| `apiKey` | `string` | `process.env.UNIRATE_API_KEY` | UniRate API key（保留在服务端）。 |
| `baseUrl` | `string` | `https://api.unirateapi.com` | API 基础 URL。 |
| `disabled` | `boolean` | `false` | 当为 `true` 时，插件将不执行任何操作，且不会添加任何 endpoint。 |
| `timeoutMs` | `number` | `30000` | 单次请求超时时间。 |
## Endpoint
插件会追加以下自定义 endpoint（Payload 会在 `/api` 前缀下提供自定义 endpoint）：
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| GET | `/api/unirate/rate?from=USD&to=EUR` | 汇率（单个汇率，或在省略 `to` 时返回基础货币的所有汇率） |
| GET | `/api/unirate/convert?from=USD&to=EUR&amount=100` | 转换金额 |
| GET | `/api/unirate/currencies` | 列出支持的货币 |
| GET | `/api/unirate/vat?country=DE` | VAT 税率（可选的国家过滤器） |
示例：
```
curl "http://localhost:3000/api/unirate/convert?from=USD&to=EUR&amount=100"
# → { "from": "USD", "to": "EUR", "amount": 100, "result": 92.00 }
```
当未配置 API key 时，endpoint 会响应 `503`（并记录警告日志），而不会在启动时崩溃。
## 货币选择字段
导出的 helper 构建了一个预填充了常见 ISO-4217 货币代码的 Payload `select` 字段：
```
import { currencyField } from "payload-plugin-unirate";
const Products = {
slug: "products",
fields: [
{ name: "title", type: "text" },
currencyField({ name: "priceCurrency", defaultValue: "USD", required: true }),
],
};
```
传入 `options: ["USD", "EUR", ...]` 可覆盖代码列表，或者从 `/api/unirate/currencies` 获取实时列表。
## 错误处理
Endpoint 响应会将上游 UniRate 错误映射到相应的 HTTP 状态码：
| 状态码 | 含义 |
|--------|---------|
| 400 | 无效的请求参数 |
| 401 | 缺少或无效的 API key |
| 403 | Endpoint 需要 Pro 订阅 |
| 404 | 未找到货币 / 无数据 |
| 429 | 超出速率限制 |
| 503 | 服务不可用 / 插件未配置 |
| 502 | 上游/传输失败 |
内部 client 及其带类型的错误类也已导出，可直接在 hook 或自定义 endpoint 中使用：
```
import { UniRateClient, AuthenticationError, RateLimitError, ProRequiredError } from "payload-plugin-unirate";
const client = new UniRateClient({ apiKey: process.env.UNIRATE_API_KEY! });
try {
const rate = await client.getRate("USD", "EUR"); // → 0.92
} catch (err) {
if (err instanceof AuthenticationError) { /* invalid key */ }
if (err instanceof RateLimitError) { /* slow down */ }
if (err instanceof ProRequiredError) { /* upgrade plan */ }
}
```
## 免费版与 Pro 版
免费版 endpoint：汇率、转换、货币、VAT 税率。历史数据和时间序列需要 [Pro 订阅](https://unirateapi.com/pricing)。
## 相关包
**UniRate API 客户端库：** [Python](https://github.com/UniRate-API/unirate-api-python) · [Node.js](https://github.com/UniRate-API/unirate-api-nodejs) · [Go](https://github.com/UniRate-API/unirate-api-go) · [Rust](https://github.com/UniRate-API/unirate-api-rust) · [Ruby](https://github.com/UniRate-API/unirate-api-ruby) · [PHP](https://github.com/UniRate-API/unirate-api-php) · [Java](https://github.com/UniRate-API/unirate-api-java) · [Swift](https://github.com/UniRate-API/unirate-api-swift) · [.NET](https://github.com/UniRate-API/unirate-api-dotnet)
**框架集成：** [Next.js](https://github.com/UniRate-API/next-unirate) · [Nuxt](https://github.com/UniRate-API/nuxt-unirate) · [SvelteKit](https://github.com/UniRate-API/sveltekit-unirate) · [Astro](https://github.com/UniRate-API/astro-unirate) · [NestJS](https://github.com/UniRate-API/nestjs-unirate) · [Eleventy](https://github.com/UniRate-API/eleventy-unirate) · [React](https://github.com/UniRate-API/react-unirate) · [Vue](https://github.com/UniRate-API/vue-unirate) · [tRPC](https://github.com/UniRate-API/trpc-unirate)
**CMS 与电商：** [WordPress](https://github.com/UniRate-API/unirate-currency-converter) · [Directus](https://github.com/UniRate-API/directus-extension-unirate) · [Strapi](https://github.com/UniRate-API/strapi-plugin-unirate) · **Payload**（本包） · [Medusa](https://github.com/UniRate-API/medusa-plugin-unirate) · [Hugo](https://github.com/UniRate-API/hugo-unirate) · [Jekyll](https://github.com/UniRate-API/jekyll-unirate)
**数据与 AI：** [LangChain Python](https://github.com/UniRate-API/langchain-unirate) · [LangChain.js](https://github.com/UniRate-API/langchain-js-unirate) · [FastAPI](https://github.com/UniRate-API/fastapi-unirate) · [Flask](https://github.com/UniRate-API/flask-unirate) · [Django REST](https://github.com/UniRate-API/djangorestframework-unirate) · [dbt](https://github.com/UniRate-API/dbt-unirate) · [Airflow](https://github.com/UniRate-API/airflow-provider-unirate)
**其他：** [MCP server](https://github.com/UniRate-API/unirate-mcp) · [CLI](https://github.com/UniRate-API/unirate-cli) · [Obsidian](https://github.com/UniRate-API/obsidian-currency) · [money gem](https://github.com/UniRate-API/money-unirate-api) · [laravel-money](https://github.com/UniRate-API/laravel-money-unirate)
## 许可证
MIT © Unirate Team
标签：MITM代理, Payload CMS, Syscall, Web开发, 插件, 数据集成, 汇率API, 自动化攻击