Initial commit: @unirate/express v0.1.0

Express 4 + 5 middleware and router for the UniRate currency-exchange API.
Attaches a typed unirate client to req.unirate, or mounts read-only proxy
routes that keep the API key server-side. Zero runtime deps; express is a
peer dependency. 52 vitest tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rob-browncc

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    environment:
+      name: npm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npm run typecheck
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ["20", "22"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npm run typecheck
+      - run: npm run build

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.tsbuildinfo
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unirate Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,196 @@
+# @unirate/express
+
+[Express](https://expressjs.com) middleware and router for the [UniRate API](https://unirateapi.com) — free currency exchange rates, conversion, and VAT rates.
+
+Attach a typed UniRate client to every request, or mount a ready-made set of JSON endpoints, and keep your API key server-side. Works with Express 4 and 5.
+
+## Features
+
+- `unirateClient()` middleware — attaches a typed `UniRateClient` to `req.unirate`
+- `unirate()` — a mountable Express `Router` with `/rate`, `/convert`, `/currencies`, `/vat` routes
+- Full error mapping — UniRate statuses (400 / 401 / 403 / 404 / 429 / 503) mirrored to proper HTTP responses; transport failures become 502; a missing key becomes 500
+- Currency-code validation + uppercasing
+- API key read from options or the `UNIRATE_API_KEY` environment variable
+- Zero runtime dependencies (uses native `fetch`); `express` is a peer dependency
+- TypeScript throughout — `req.unirate` is typed via Express module augmentation
+- ESM + CJS builds
+
+## Install
+
+```bash
+npm install @unirate/express express
+```
+
+`express` is a peer dependency (`>=4.0.0`, works with v4 and v5). Requires Node 18+ for native `fetch`. Get a free UniRate API key at [unirateapi.com](https://unirateapi.com).
+
+## Quick start
+
+### Middleware
+
+```ts
+import express from "express";
+import { unirateClient } from "@unirate/express";
+
+const app = express();
+app.use(unirateClient()); // reads process.env.UNIRATE_API_KEY
+
+app.get("/eur", async (req, res) => {
+  const rate = await req.unirate.getRate("USD", "EUR");
+  res.json({ pair: "USD/EUR", rate });
+});
+
+app.listen(3000);
+```
+
+`req.unirate` is fully typed via Express's `Request` interface — no casting needed.
+
+### Router
+
+```ts
+import express from "express";
+import { unirate } from "@unirate/express";
+
+const app = express();
+app.use("/api/unirate", unirate());
+```
+
+That mounts:
+
+```
+GET /api/unirate/rate?from=USD&to=EUR
+GET /api/unirate/convert?from=USD&to=EUR&amount=100
+GET /api/unirate/currencies
+GET /api/unirate/vat?country=DE
+```
+
+## Options
+
+Both `unirateClient()` and `unirate()` accept the same options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | — | API key. If omitted, resolved from the env variable |
+| `envKey` | `string` | `"UNIRATE_API_KEY"` | Name of the env variable to read the key from |
+| `baseUrl` | `string` | `https://api.unirateapi.com` | Override the API base URL |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Inject a custom `fetch` |
+| `timeoutMs` | `number` | `30000` | Request timeout |
+| `userAgent` | `string` | `@unirate/express/<version>` | Custom User-Agent header |
+
+```ts
+app.use(unirateClient({ apiKey: process.env.UNIRATE_API_KEY }));
+// or a custom env variable name
+app.use("/fx", unirate({ envKey: "MY_UNIRATE_KEY" }));
+```
+
+## Routes
+
+### `GET /rate`
+
+| Param | Required | Default | Description |
+|---|---|---|---|
+| `from` | no | `USD` | Source currency (3-letter ISO code) |
+| `to` | no | — | Target currency. Omit to return all rates for `from` |
+
+```jsonc
+// /rate?from=USD&to=EUR  →
+{ "rate": 0.92 }
+// /rate?from=USD  →
+{ "rates": { "EUR": 0.92, "GBP": 0.79 } }
+```
+
+### `GET /convert`
+
+| Param | Required | Default | Description |
+|---|---|---|---|
+| `from` | no | `USD` | Source currency |
+| `to` | yes | — | Target currency |
+| `amount` | no | `1` | Amount to convert (positive number) |
+
+```jsonc
+// /convert?from=USD&to=EUR&amount=100  →
+{ "result": 92.5 }
+```
+
+### `GET /currencies`
+
+```jsonc
+{ "currencies": ["USD", "EUR", "GBP", "..."] }
+```
+
+### `GET /vat`
+
+| Param | Required | Default | Description |
+|---|---|---|---|
+| `country` | no | — | ISO-3166 alpha-2 code. Omit for all countries |
+
+```jsonc
+// /vat?country=DE  →
+{ "country": "DE", "vat_data": { "country_code": "DE", "country_name": "Germany", "vat_rate": 19 } }
+```
+
+## Using the client directly
+
+The internal client is exported for direct use in your own handlers:
+
+```ts
+import { UniRateClient, RateLimitError } from "@unirate/express";
+
+const client = new UniRateClient({ apiKey: "..." });
+
+try {
+  const rate = await client.getRate("USD", "EUR");        // number
+  const all = await client.getRate("USD");                // Record<string, number>
+  const eur = await client.convert("EUR", 100, "USD");    // number
+  const codes = await client.getSupportedCurrencies();    // string[]
+  const vat = await client.getVatRate("DE");              // { country, vat_data }
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    // back off and retry
+  }
+}
+```
+
+It is also available on the `@unirate/express/client` subpath if you want the client without pulling in the Express glue.
+
+## Error handling
+
+The router maps thrown errors to HTTP responses with a `{ "error": string }` body:
+
+| Status | Meaning |
+|---|---|
+| `400` | Invalid parameter (bad currency/country code, missing/invalid amount) |
+| `401` | Missing or invalid API key |
+| `403` | Endpoint requires a Pro subscription |
+| `404` | Currency not found or no data available |
+| `429` | Rate limit exceeded |
+| `500` | API key not configured on the server |
+| `502` | UniRate upstream / transport error |
+| `503` | Service unavailable |
+
+When using the client directly, these map to typed error classes — all extending `UniRateError`:
+`InvalidRequestError`, `AuthenticationError`, `ProRequiredError`, `InvalidCurrencyError`, `RateLimitError`, `ServiceUnavailableError`.
+
+## Free vs Pro tier
+
+The free tier covers `/rate`, `/convert`, `/currencies`, and `/vat`. Historical and time-series endpoints require a [Pro subscription](https://unirateapi.com/pricing) and are not exposed by this package.
+
+## Example
+
+A runnable Express app lives in [`examples/server.mjs`](./examples/server.mjs):
+
+```bash
+npm run build
+UNIRATE_API_KEY=your-key node examples/server.mjs
+```
+
+## Related packages
+
+**UniRate API client libraries:** [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)
+
+**Framework integrations:** [Fastify](https://github.com/UniRate-API/fastify-unirate) · [Hono](https://github.com/UniRate-API/hono-unirate) · [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) · [Remix](https://github.com/UniRate-API/remix-unirate) · [Angular](https://github.com/UniRate-API/angular-unirate) · [Vue](https://github.com/UniRate-API/vue-unirate) · [React](https://github.com/UniRate-API/react-unirate)
+
+**Platform:** [Cloudflare Workers](https://github.com/UniRate-API/cloudflare-workers-unirate) · [MCP server](https://github.com/UniRate-API/unirate-mcp) · [CLI](https://github.com/UniRate-API/unirate-cli)
+
+## License
+
+MIT © Unirate Team

examples/server.mjs

@@ -0,0 +1,47 @@
+// Runnable example. Requires a built dist/ (npm run build) and a key:
+//
+//   UNIRATE_API_KEY=your-key node examples/server.mjs
+//
+// Then:
+//   curl 'http://localhost:3000/api/unirate/rate?from=USD&to=EUR'
+//   curl 'http://localhost:3000/api/unirate/convert?from=USD&to=EUR&amount=100'
+//   curl 'http://localhost:3000/api/unirate/currencies'
+//   curl 'http://localhost:3000/api/unirate/vat?country=DE'
+//   curl 'http://localhost:3000/price'   # uses the attached req.unirate client
+
+import express from "express";
+import { unirate, unirateClient } from "../dist/index.js";
+
+const apiKey = process.env.UNIRATE_API_KEY;
+if (!apiKey) {
+  console.error("Set UNIRATE_API_KEY in your environment first.");
+  process.exit(1);
+}
+
+const app = express();
+
+// 1) Mount the ready-made JSON proxy routes. The API key stays server-side.
+app.use("/api/unirate", unirate({ apiKey }));
+
+// 2) Attach a typed client to every request as `req.unirate`, then use it
+//    directly in your own handlers.
+app.use(unirateClient({ apiKey }));
+
+app.get("/price", async (req, res, next) => {
+  try {
+    const rate = await req.unirate.getRate("USD", "EUR");
+    const converted = await req.unirate.convert("EUR", 100, "USD");
+    const currencies = await req.unirate.getSupportedCurrencies();
+    res.json({
+      usd_to_eur: rate,
+      "100_usd_in_eur": converted,
+      supported_count: currencies.length,
+    });
+  } catch (err) {
+    next(err);
+  }
+});
+
+app.listen(3000, () => {
+  console.log("Listening on http://localhost:3000");
+});