Initial release v0.1.0

UniRate Currency: inline live and historical exchange rates for Obsidian.
- Inline syntax: `usd:eur`, `usd:eur:100`, `100 usd:eur`, with `:`, `>`, or `→`
- Commands: Insert exchange rate, Convert selection, Clear cache
- Settings: API key, default base currency, rate/money decimals, cache TTLs
- 35 jest tests (parser, cache, format, client)
- Built with esbuild against the official sample-plugin scaffold

Author: rob-browncc

.github/workflows/ci.yml

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

.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+
+      - name: Create release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          gh release create "$TAG" \
+            --title="$TAG" \
+            --notes="Release $TAG. See README for install/upgrade." \
+            main.js manifest.json styles.css

.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+main.js
+*.log
+.DS_Store
+.idea/
+.vscode/
+coverage/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 UniRate API
+Copyright (c) 2026 UniRate-API
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -0,0 +1,65 @@
+# UniRate Currency for Obsidian
+
+Inline live and historical currency exchange rates in your notes.
+
+Type `` `usd:eur` `` and the plugin renders the current USD→EUR rate where the inline code used to be. Type `` `usd:eur:100` `` and it renders the converted amount. 170+ currencies plus the major cryptocurrencies, with daily history back to 1999 (Pro plan).
+
+Powered by [UniRateAPI](https://unirateapi.com).
+
+## Why
+
+Existing Obsidian finance plugins are either crypto-only (`obsidian-crypto-lookup`) or general-purpose calculators that happen to handle currency (`obsidian-numerals`). Neither gives you inline, in-line live rates in normal prose. A [2022 forum thread](https://forum.obsidian.md/) asking for one is still open.
+
+## Install
+
+Until the plugin is approved on the community plugins list, install manually:
+
+1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/UniRate-API/obsidian-currency/releases).
+2. Drop them into `<your vault>/.obsidian/plugins/unirate-currency/`.
+3. Reload Obsidian and enable **UniRate Currency** under Settings → Community plugins.
+4. Open the **UniRate Currency** tab and paste your API key (get a [free key](https://unirateapi.com/register)).
+
+## Syntax
+
+All forms go inside a single inline code span (`` `…` ``):
+
+| You write | Renders as |
+|---|---|
+| `` `usd:eur` `` | `0.9234 EUR/USD` |
+| `` `usd:eur:100` `` | `92.34 EUR` |
+| `` `100 usd:eur` `` | `92.34 EUR` |
+| `` `gbp>jpy` `` | `198.42 JPY/GBP` |
+| `` `usd→eur` `` | `0.9234 EUR/USD` |
+
+- Currency codes can be 3-5 characters, case-insensitive (`USDT`, `BTC`, `XAU`).
+- Decimal places, thousand-grouping, and the appended currency code are all configurable.
+- Rates are cached in memory for 60 minutes by default to avoid hammering the API.
+
+## Commands
+
+- **Insert exchange rate** — opens a modal to pick from/to/amount/date and inserts the result at the cursor.
+- **Convert selection** — select something like `100 USD to EUR` (or `100 usd:eur`) and run the command to replace the selection with the converted value.
+- **Clear rate cache** — drop the in-memory cache; the next render will re-fetch.
+
+## Pricing
+
+UniRateAPI's free tier covers live rates and supports 170+ currencies. Historical rates and commodities (`XAU`, `XAG`, `XPT`, `XPD`) require a [Pro plan](https://unirateapi.com/pricing).
+
+## Disclosure
+
+This plugin is built and maintained by UniRateAPI. If you'd rather use a different rate source, the inline syntax is generic enough that another plugin could implement it the same way — open an issue if you'd find that useful.
+
+## Development
+
+```bash
+npm install
+npm run dev      # esbuild watch
+npm run build    # tsc + esbuild production
+npm test         # jest unit tests
+```
+
+The plugin uses Obsidian's `requestUrl` API so it works on both desktop and mobile without CORS workarounds.
+
+## License
+
+MIT. See `LICENSE`.

__tests__/__mocks__/obsidian.ts

@@ -0,0 +1,68 @@
+export const requestUrl = jest.fn(async (_opts: unknown) => ({
+	status: 200,
+	headers: {},
+	arrayBuffer: new ArrayBuffer(0),
+	text: "{}",
+	json: {},
+}));
+
+export class Notice {
+	constructor(_message: string) {}
+}
+
+export class Modal {
+	app: unknown;
+	contentEl = { empty: () => undefined, createEl: () => undefined };
+	constructor(app: unknown) {
+		this.app = app;
+	}
+	open(): void {}
+	close(): void {}
+}
+
+export class Plugin {
+	app: unknown;
+	manifest: unknown;
+	constructor(app?: unknown, manifest?: unknown) {
+		this.app = app;
+		this.manifest = manifest;
+	}
+}
+
+export class PluginSettingTab {
+	app: unknown;
+	plugin: unknown;
+	containerEl: { empty: () => void } = { empty: () => undefined };
+	constructor(app: unknown, plugin: unknown) {
+		this.app = app;
+		this.plugin = plugin;
+	}
+	display(): void {}
+}
+
+export class Setting {
+	constructor(_containerEl: unknown) {}
+	setName(): this {
+		return this;
+	}
+	setDesc(): this {
+		return this;
+	}
+	addText(): this {
+		return this;
+	}
+	addToggle(): this {
+		return this;
+	}
+	addSlider(): this {
+		return this;
+	}
+	addButton(): this {
+		return this;
+	}
+}
+
+export type App = unknown;
+export type Editor = unknown;
+export type MarkdownView = unknown;
+export type MarkdownPostProcessorContext = unknown;

__tests__/cache.test.ts

@@ -0,0 +1,45 @@
+import { TTLCache } from "../src/cache";
+
+describe("TTLCache", () => {
+	test("returns set value before TTL expires", () => {
+		let now = 1_000_000;
+		const cache = new TTLCache<number>(() => now);
+		cache.set("k", 42, 60_000);
+		now += 30_000;
+		expect(cache.get("k")).toBe(42);
+	});
+
+	test("evicts after TTL expires", () => {
+		let now = 1_000_000;
+		const cache = new TTLCache<number>(() => now);
+		cache.set("k", 42, 60_000);
+		now += 60_001;
+		expect(cache.get("k")).toBeUndefined();
+		expect(cache.size()).toBe(0);
+	});
+
+	test("returns undefined for unknown key", () => {
+		const cache = new TTLCache<number>();
+		expect(cache.get("missing")).toBeUndefined();
+	});
+
+	test("clear empties the store", () => {
+		const cache = new TTLCache<number>();
+		cache.set("a", 1, 1000);
+		cache.set("b", 2, 1000);
+		expect(cache.size()).toBe(2);
+		cache.clear();
+		expect(cache.size()).toBe(0);
+		expect(cache.get("a")).toBeUndefined();
+	});
+
+	test("overwrites existing key with fresh TTL", () => {
+		let now = 1_000_000;
+		const cache = new TTLCache<number>(() => now);
+		cache.set("k", 1, 1000);
+		now += 500;
+		cache.set("k", 2, 1000);
+		now += 800;
+		expect(cache.get("k")).toBe(2);
+	});
+});

__tests__/client.test.ts

@@ -0,0 +1,105 @@
+import { requestUrl } from "obsidian";
+import { UniRateClient, UniRateClientError } from "../src/client";
+
+const mockedRequestUrl = requestUrl as unknown as jest.Mock;
+
+function makeResponse(body: unknown, status = 200) {
+	return {
+		status,
+		headers: {},
+		arrayBuffer: new ArrayBuffer(0),
+		text: JSON.stringify(body),
+		json: body,
+	};
+}
+
+describe("UniRateClient", () => {
+	beforeEach(() => {
+		mockedRequestUrl.mockReset();
+	});
+
+	test("getRate hits /api/rates and returns the target rate", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({ rates: { EUR: 0.92 } }));
+		const c = new UniRateClient("k");
+		expect(await c.getRate("USD", "EUR")).toBe(0.92);
+		const call = mockedRequestUrl.mock.calls[0][0];
+		expect(call.url).toContain("/api/rates");
+		expect(call.url).toContain("from=USD");
+		expect(call.url).toContain("to=EUR");
+		expect(call.url).toContain("api_key=k");
+	});
+
+	test("getRate routes to historical endpoint when date is given", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({ rates: { EUR: 0.91 } }));
+		const c = new UniRateClient("k");
+		expect(await c.getRate("USD", "EUR", "2024-01-15")).toBe(0.91);
+		expect(mockedRequestUrl.mock.calls[0][0].url).toContain("/api/historical/rates");
+		expect(mockedRequestUrl.mock.calls[0][0].url).toContain("date=2024-01-15");
+	});
+
+	test("convert multiplies amount by rate", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({ rates: { EUR: 0.5 } }));
+		const c = new UniRateClient("k");
+		const r = await c.convert("USD", "EUR", 100);
+		expect(r.rate).toBe(0.5);
+		expect(r.result).toBe(50);
+	});
+
+	test("throws AuthenticationError-style on 401", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({}, 401));
+		const c = new UniRateClient("bad");
+		await expect(c.getRate("USD", "EUR")).rejects.toMatchObject({
+			name: "UniRateClientError",
+			status: 401,
+		});
+	});
+
+	test("throws on 403 with Pro-plan message", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({}, 403));
+		const c = new UniRateClient("k");
+		await expect(c.getRate("USD", "XAU", "2024-01-15")).rejects.toMatchObject({
+			status: 403,
+			message: expect.stringContaining("Pro"),
+		});
+	});
+
+	test("throws on 429", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({}, 429));
+		const c = new UniRateClient("k");
+		await expect(c.getRate("USD", "EUR")).rejects.toMatchObject({ status: 429 });
+	});
+
+	test("throws on 404", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({}, 404));
+		const c = new UniRateClient("k");
+		await expect(c.getRate("USD", "ZZZ")).rejects.toMatchObject({ status: 404 });
+	});
+
+	test("throws when API key is missing", async () => {
+		const c = new UniRateClient("");
+		await expect(c.getRate("USD", "EUR")).rejects.toBeInstanceOf(UniRateClientError);
+		expect(mockedRequestUrl).not.toHaveBeenCalled();
+	});
+
+	test("listCurrencies sorts and returns the list", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(
+			makeResponse({ currencies: ["EUR", "USD", "GBP"] }),
+		);
+		const c = new UniRateClient("k");
+		expect(await c.listCurrencies()).toEqual(["EUR", "GBP", "USD"]);
+	});
+
+	test("throws when /api/rates response is missing target", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({ rates: { JPY: 150 } }));
+		const c = new UniRateClient("k");
+		await expect(c.getRate("USD", "EUR")).rejects.toBeInstanceOf(UniRateClientError);
+	});
+
+	test("sends Accept: application/json header (workaround for /api/currencies HTML 404)", async () => {
+		mockedRequestUrl.mockResolvedValueOnce(makeResponse({ currencies: ["USD"] }));
+		const c = new UniRateClient("k");
+		await c.listCurrencies();
+		const call = mockedRequestUrl.mock.calls[0][0];
+		expect(call.headers).toMatchObject({ Accept: "application/json" });
+	});
+});

__tests__/format.test.ts

@@ -0,0 +1,36 @@
+import { formatMoney, formatRate } from "../src/format";
+
+describe("formatRate", () => {
+	test("rounds to requested decimals", () => {
+		expect(formatRate(0.923456, 4)).toBe("0.9235");
+		expect(formatRate(0.923456, 2)).toBe("0.92");
+	});
+
+	test("pads zeroes for short values", () => {
+		expect(formatRate(1, 4)).toBe("1.0000");
+	});
+
+	test("does not use thousand separators", () => {
+		expect(formatRate(12345.678, 2)).toBe("12345.68");
+	});
+
+	test("clamps absurd decimal counts", () => {
+		expect(formatRate(1, 99)).toBe("1.0000000000");
+		expect(formatRate(1, -5)).toBe("1");
+	});
+
+	test("handles NaN/Infinity", () => {
+		expect(formatRate(NaN, 2)).toBe("NaN");
+		expect(formatRate(Infinity, 2)).toBe("Infinity");
+	});
+});
+
+describe("formatMoney", () => {
+	test("appends currency code", () => {
+		expect(formatMoney(92.34, "EUR", 2)).toBe("92.34 EUR");
+	});
+
+	test("uppercases nothing, trusts caller", () => {
+		expect(formatMoney(100, "USD", 0)).toBe("100 USD");
+	});
+});