magpie-page-token-widget 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liuzq
+
+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.

package/NOTICE

@@ -0,0 +1,22 @@
+# Third-party notices
+
+## Magpie
+
+[Magpie](https://github.com/yetone/magpie), MIT, supplies the local observation APIs used at runtime. No Magpie source, account configuration or provider credentials are bundled. The product is independently implemented and is not an official Magpie client.
+
+## ScriptableTokenWidgets
+
+[liuzq1103/ScriptableTokenWidgets](https://github.com/liuzq1103/ScriptableTokenWidgets), MIT, copyright 2026 liuzq1103. The collector, the projection of the snapshot and the widget script of the phone are taken from that project and are changed for this plugin. The same licence and the same author apply.
+
+## Reference projects
+
+- [DaleXiao/ScriptableTokenWidgets](https://github.com/DaleXiao/ScriptableTokenWidgets): inspiration for the iPhone widget concept. No source files copied.
+- [Hj714110-oss/ScriptableTokenTrackerV2](https://github.com/Hj714110-oss/ScriptableTokenTrackerV2): MIT, copyright 2026 Hj714110-oss. Reviewed for feature organization and Scriptable caching approaches. No source files copied.
+
+## Bundled libraries
+
+- [qrcode-generator](https://github.com/kazuhikoarase/qrcode-generator), MIT, copyright 2009 Kazuhiko Arase. The library is vendored at `lib/vendor/qrcode-generator.cjs` so that the plugin carries no dependency that has to be installed.
+
+## Runtime applications
+
+Scriptable, Tailscale and Magpie are separately installed applications with their own licences and terms. OpenAI, MiniMax and GLM names identify the subscriptions observed through Magpie. No proprietary logo assets or model lists are bundled.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# magpie-page-token-widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 iPhone 桌面的额度组件接进 Magpie：装上这个插件，扫一次码，手机上就能显示 Codex、MiniMax、GLM 各家套餐的剩余额度与真实 Token 用量。
+
+装这个插件不需要再跑安装脚本、装 Node.js、建计划任务或开 Tailscale 端口转发。插件自己把服务跑起来，自己找到尾网地址，手机扫一次码就配对好了。
+
+> 数据来自你自己的 Magpie，脚本里不含任何密钥。组件显示的仍是 Magpie 的口径。
+
+![插件页面](docs/console.png)
+
+## 它做什么
+
+- 插件页给出一个二维码。用 iPhone 的相机扫一下，Safari 打开配对页，下载组件脚本，用 Scriptable 打开它，长按桌面加组件就行了。
+- 组件里显示每家订阅的剩余额度、5 小时与周额度窗口的百分比、重置倒计时、今日 Token、七日趋势和各家排行。参数可以选订阅（`codex`、`minimax`、`glm`，或 `codex@账号名`），也可以把百分比换成已用（`|used`）。
+- 插件页还能改中号和大号组件里显示哪些订阅，能看到 Tailscale 的状态和同一尾网里的 iPhone。
+  - 勾一个厂商＝这个厂商的所有账号都显示；只勾一个账号＝只有这个账号。勾选框显示的就是手机上会出现的卡片。
+- 服务只读 Magpie 的本地接口，只在本机打开，手机经 Tailscale 的端口转发进来，令牌存放在 Magpie 自己的目录里。
+
+## 需要什么
+
+- Magpie（桌面版，插件宿主是 Bun）。
+- Tailscale：电脑和 iPhone 都在同一个尾网里，插件靠它找到地址。
+- iPhone 上的 [Scriptable](https://scriptable.app/)。
+
+## 安装
+
+在 Magpie 里打开插件页，或者用命令行：
+
+```bash
+magpie plugin add magpie-page-token-widget
+```
+
+从源码装：
+
+```bash
+magpie plugin add ./magpie-page-token-widget
+```
+
+## 配对
+
+1. 在 Magpie 里打开「插件 → iPhone 额度组件」。
+2. 插件页会显示 Tailscale 的状态。电脑和 iPhone 都在同一个尾网里时，这里会显示尾网地址和一张二维码。
+3. iPhone 用相机扫码，在 Safari 里打开配对页，点「下载组件脚本」。
+4. 在「文件」App 里打开刚下载的 `UsageWidget.js`，选「共享 → 用 Scriptable 打开」。
+5. 长按 iPhone 桌面空白处，添加 Scriptable 小组件，选择 `UsageWidget`。
+
+配对码只能用一次。手机装好组件后码就失效了；再生成一个就能装第二台。脚本里只有一个一次性配对码，第一次运行时换成自己的令牌，存进 Scriptable 的钥匙串。
+
+不想扫码也行：插件页上有「只读令牌」，把它和「服务地址」填进 `scriptable/SetupUsageWidget.js`（在 Scriptable 里新建一个脚本粘贴运行）也行。
+
+## 组件参数
+
+| 尺寸 | 内容 | Widget Parameter |
+|---|---|---|
+| 小号 | 单家额度、重置倒计时、今日 Token | `codex`（默认）、`minimax`、`glm`；某账号写作 `codex@账号名`；加 `|used` 改显已用 |
+| 中号 | 每页最多 6 个；1–4 个并排，5–6 个两行三列；今日 Token | 留空；`page=2` 查看第二页 |
+| 大号 | 每页最多 6 个；两列卡片，显示主额度、重置时间及第二窗口百分比；今日与近七日 Token | 留空；`page=2` 查看第二页 |
+
+## 生命周期
+
+组件随 Magpie 运行。关掉 Magpie 之后，手机上显示的是最后一次拿到的结果，重新打开 Magpie 就会更新。这和原来那个用计划任务常驻的服务不同，是"插件"这个形态的取舍。
+
+## 端口
+
+服务默认听 8790。端口上冲突时换一个：
+
+```bash
+magpie plugin options magpie-page-token-widget '{"port":8890}'
+```
+
+改完要重启 Magpie。插件会在尾网里给这个端口建一条转发（`tailscale serve --tcp`），手机从 100.x 地址连进来；端口上已经有别人的转发时，插件不会动它。
+
+转发指向的是手机那一侧的端口（默认比服务端口大 1，即 8791），控制台留在 127.0.0.1:8790。尾网里的请求落在这条转发上，不会被当成本机的请求，所以手机看不到控制台，也拿不到令牌。
+
+`tailscale serve --bg --tcp=8790` 是 Tailscale 里的长期设置：它留在那儿，插件被移除或崩溃都不会自己消失，只有插件正常卸载时才会撤掉。想知道现在有哪些转发，看 `tailscale serve status`。
+
+## 卸载
+
+```bash
+magpie plugin rm magpie-page-token-widget
+```
+
+插件被移除时，它建的转发会一并撤掉。
+
+## 隐私
+
+- 服务只读 Magpie 的本地接口（`127.0.0.1:3425`），不写 Magpie 的配置，不碰登录信息。
+- 令牌是本机随机生成的，只读，存在 Magpie 的配置目录里；只有本机的插件页和拿着配对码的手机能拿到。
+- 服务只在本机（127.0.0.1）上监听，手机是经 Tailscale 的转发进来的，没有公网入口，也不需要防火墙规则。
+
+## 开发
+
+```bash
+node --test test/service.test.mjs
+```
+
+`lib/collector.mjs` 和 `lib/normalize.mjs` 来自 [ScriptableTokenWidgets](https://github.com/liuzq1103/ScriptableTokenWidgets)，`lib/vendor/qrcode-generator.cjs` 是 [qrcode-generator](https://github.com/kazuhikoarase/qrcode-generator)。详见 [NOTICE](NOTICE)。
+
+---
+
+# magpie-page-token-widget (English)
+
+An iPhone home screen widget for Magpie, brought in as a plugin: install the plugin, scan a code, and the widget shows the remaining quota and the real token usage of Codex, MiniMax and GLM.
+
+Installing it needs no install script, no Node.js, no scheduled task and no Tailscale port forwarding. The plugin runs the service itself, finds the tailnet address itself, and the phone pairs by scanning a code once.
+
+## Requirements
+
+- Magpie on the desktop (the plugin host is Bun).
+- Tailscale, with the computer and the iPhone in the same tailnet.
+- [Scriptable](https://scriptable.app/) on the iPhone.
+
+## Install
+
+```bash
+magpie plugin add magpie-page-token-widget
+```
+
+From a checkout: `magpie plugin add ./magpie-page-token-widget`.
+
+## Pair
+
+1. Open the plugin page in Magpie.
+2. The page shows the state of Tailscale. When the computer and the iPhone share a tailnet it shows the tailnet address and a code to scan.
+3. Scan the code with the camera of the iPhone, open the page in Safari and download the widget script.
+4. Open the downloaded `UsageWidget.js` in the Files app and choose "Share → Open with Scriptable".
+5. Long press the home screen, add the Scriptable widget and pick `UsageWidget`.
+
+The pairing code works once. The script carries only that one-time code; on its first run it exchanges the code for a token of its own and keeps it in the keychain of Scriptable.
+
+## Widget parameter
+
+| Size | Shows | Widget Parameter |
+|---|---|---|
+| Small | one quota, the reset countdown, today's tokens | `codex` (default), `minimax`, `glm`; one account is written `codex@<account>`; `\|used` shows what is used |
+| Medium | up to 6 per page; today's tokens | empty; `page=2` for the second page |
+| Large | up to 6 per page; two columns with the quota, the reset and the second window; today's and the last seven days | empty; `page=2` for the second page |
+
+## Lifetime
+
+The service runs as long as Magpie runs. With Magpie closed, the phone keeps the last result it received.
+
+## Port
+
+The service listens on 8790 by default. Pick another one when the port is taken:
+
+```bash
+magpie plugin options magpie-page-token-widget '{"port":8890}'
+```
+
+Restart Magpie afterwards. The plugin publishes the port in the tailnet with a forwarding of Tailscale (`tailscale serve --tcp`), so the phone reaches it on the 100.x address. A forwarding of another service on that port is never touched.
+
+The forwarding points at the phone side of the service (by default one port above the service port, so 8791), while the console stays on 127.0.0.1:8790. A request that comes in through the tailnet lands on that phone port and is never taken for a request of this computer, so the phone cannot read the console or the token.
+
+`tailscale serve --bg --tcp=8790` is a standing setting of Tailscale: it stays there when the plugin is removed or crashes, and only a clean uninstall takes it away. `tailscale serve status` shows what is published right now.
+
+## Uninstall
+
+```bash
+magpie plugin rm magpie-page-token-widget
+```
+
+The forwarding of the plugin is taken away with it.
+
+## Privacy
+
+The service only reads the local API of Magpie (`127.0.0.1:3425`). The token is random, read only and stays in the directory of Magpie. The service listens on this computer only (127.0.0.1); the phone comes in through the forwarding of Tailscale. There is no public entrance and no firewall rule is needed.
+
+## Development
+
+```bash
+node --test test/service.test.mjs
+```

package/index.mjs

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { startServer } from './lib/server.mjs';
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+
+let running;
+let current;
+
+// The host calls this again when the options change, and calls it once when
+// the plugin is loaded. The service is restarted whenever the hand-over
+// changes, so a new port or a new gateway takes effect.
+export default {
+  id: 'token-widget',
+  async server(input, options) {
+    if (!input?.directory) throw new Error('The Magpie plugin host is required.');
+    options ||= {};
+    const wanted = JSON.stringify([input.directory, options]);
+    if (wanted !== current) {
+      const previous = running;
+      current = wanted;
+      running = (async () => {
+        await (await previous?.catch(() => null))?.close();
+        return startServer({
+          root,
+          dataDir: path.join(input.directory, 'token-widget'),
+          magpieDir: input.directory,
+          options,
+        });
+      })();
+      running.catch(() => {
+        if (current === wanted) current = undefined;
+      });
+    }
+    await running;
+    return {};
+  },
+};

package/lib/collector.mjs

@@ -0,0 +1,123 @@
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveQuotas, normalizeUsage, project, shanghaiDay, sanitizeCachedLabels, providerFamily, accountKey, number } from './normalize.mjs';
+
+export class Collector {
+  constructor({ upstream, magpieDir, snapshotFile, fetcher = fetch, clock = Date.now, display = {} }) {
+    Object.assign(this, { upstream, magpieDir, snapshotFile, fetcher, clock });
+    this.display = display;
+    this.snapshot = { version: 1, parts: {}, failures: {} };
+    this.pending = null;
+    // The address of every account, kept in memory only: it is never written
+    // to the snapshot and never leaves this machine.
+    this.addresses = new Map();
+    // The last reading of every account, kept in memory only as well.
+    this.usage = new Map();
+  }
+  async load() {
+    try {
+      const saved = JSON.parse(await readFile(this.snapshotFile, 'utf8'));
+      if (saved.version === 1 && saved.parts && saved.failures) {
+        for (const key of Object.keys(saved.parts)) {
+          saved.parts[key].data = sanitizeCachedLabels(saved.parts[key].data, key);
+          saved.failures[key] = true; // Await live revalidation after every process restart.
+        }
+        this.snapshot = saved;
+      }
+    } catch { /* A new or damaged cache must not prevent startup. */ }
+  }
+  async request(endpoint, timeout = 15_000) {
+    const result = await this.fetcher(new URL(endpoint, this.upstream), {
+      signal: AbortSignal.timeout(timeout), headers: { Accept: 'application/json' }, redirect: 'error',
+    });
+    if (!result.ok) throw new Error('Magpie unavailable');
+    return result.json();
+  }
+  async quotaCache() {
+    try { return JSON.parse(await readFile(path.join(this.magpieDir, 'quotas.json'), 'utf8')); }
+    catch { return {}; }
+  }
+  async quotas() {
+    const [response, cache] = await Promise.allSettled([
+      this.request('/v1/magpie/quotas?kept=1'), this.quotaCache(),
+    ]);
+    const raw = response.status === 'fulfilled' ? response.value : null;
+    const cards = resolveQuotas(raw, cache.status === 'fulfilled' ? cache.value : {}, this.snapshot.parts.quotas?.data || []);
+    await this.accountUsage(raw, cards);
+    return cards;
+  }
+  // An account's own usage is asked for by the address Magpie reports for it.
+  // The address goes into the query of the local gateway and only the totals
+  // come back, so it never leaves this machine and is never stored.
+  async accountUsage(raw, cards) {
+    const fresh = new Map();
+    for (const card of raw?.data || []) {
+      const family = providerFamily(card?.provider);
+      const address = typeof (card?.user ?? card?.account) === 'string' ? (card.user ?? card.account).trim() : '';
+      if (!family || !address.includes('@')) continue;
+      // The key of the account is the one of its card, so a query can never
+      // reach the reading of another account.
+      const key = accountKey(family, address);
+      if (!key) continue;
+      const known = fresh.get(key);
+      // Two accounts of one vendor that share the same name cannot be told
+      // apart: their usage stays unknown instead of being taken from the wrong
+      // one.
+      if (known === null) continue;
+      if (known && known !== address) { fresh.set(key, null); continue; }
+      fresh.set(key, address);
+    }
+    // The addresses of the last successful reading are kept in memory only, so
+    // the usage of an account survives a quota outage. They are never written
+    // to the snapshot.
+    if (fresh.size) this.addresses = new Map([...this.addresses, ...fresh]);
+    await Promise.all(cards.filter(card => card.account).map(async card => {
+      const address = this.addresses.get(card.id);
+      if (!address) return;
+      try {
+        // A short timeout: the reading of the quotas must not wait long for a
+        // usage query that only fills in one number.
+        const data = await this.request('/v1/magpie/usage/requests?period=today&limit=1&account=' + encodeURIComponent(address), 5000);
+        if (!['input', 'output', 'cache_read', 'cache_write', 'calls'].every(key =>
+          typeof data[key] === 'number' && Number.isFinite(data[key]))) throw new Error('Not a usage answer');
+        const total = number(data.input) + number(data.output) + number(data.cache_read) + number(data.cache_write);
+        const usage = { today: { totalTokens: total, requests: number(data.calls) } };
+        card.accountUsage = usage;
+        this.usage.set(card.id, usage);
+      } catch {
+        // The last reading of this account is kept: a number that was read a
+        // minute ago is better than no number at all.
+        card.accountUsage = card.accountUsage || this.usage.get(card.id) || null;
+      }
+    }));
+  }
+  refresh() {
+    if (this.pending) return this.pending;
+    this.pending = this.collect().finally(() => { this.pending = null; });
+    return this.pending;
+  }
+  async collect() {
+    const jobs = {
+      quotas: () => this.quotas(),
+      today: async () => normalizeUsage(await this.request('/v1/magpie/usage/requests?period=today&limit=1')),
+      week: async () => normalizeUsage(await this.request('/v1/magpie/usage/requests?period=7d&limit=1')),
+    };
+    await Promise.all(Object.entries(jobs).map(async ([key, job]) => {
+      try {
+        const periodDay = shanghaiDay(this.clock());
+        const data = await job();
+        this.snapshot.parts[key] = { observedAt: new Date(this.clock()).toISOString(), periodDay, data };
+        if (key === 'quotas' && data.every(card => card.stale)) this.snapshot.failures[key] = true;
+        else delete this.snapshot.failures[key];
+      } catch { this.snapshot.failures[key] = true; }
+    }));
+    try {
+      await mkdir(path.dirname(this.snapshotFile), { recursive: true });
+      await writeFile(this.snapshotFile + '.tmp', JSON.stringify(this.snapshot), { mode: 0o600 });
+      await rename(this.snapshotFile + '.tmp', this.snapshotFile);
+    } catch { console.warn('Snapshot could not be saved; serving the in-memory snapshot.'); }
+  }
+  overview() { return project(this.snapshot, this.clock(), this.display); }
+  // The console shows every account, not only the ones on the home screen.
+  overviewWith(display) { return project(this.snapshot, this.clock(), display); }
+}

package/lib/forward.mjs

@@ -0,0 +1,67 @@
+import { call } from './tailnet.mjs';
+
+// The phone reaches the service through a forwarding of Tailscale: the port
+// of the service is published inside the tailnet and points at this computer.
+// The forwarding of another service on the same port is never touched.
+//
+// The published port and the port it points at are not the same one. The
+// console of this computer keeps the published port on the loopback address,
+// and the phone side gets a port of its own, so a request that arrives
+// through the tailnet can never be mistaken for one from this computer.
+export const targetFor = port => '127.0.0.1:' + port;
+
+export async function serveState() {
+  const result = await call(['serve', 'status', '--json']);
+  if (!result.ok) return { ok: false, error: result.error };
+  try {
+    return { ok: true, data: JSON.parse(result.stdout) };
+  } catch {
+    return { ok: false, error: 'tailscale serve status did not answer with JSON.' };
+  }
+}
+
+// The status of Tailscale lists the published ports under "TCP".
+export const publishedFor = (status, port) => status?.data?.TCP?.[String(port)] || null;
+
+export async function planForward(publishedPort, phonePort) {
+  const status = await serveState();
+  if (!status.ok) return { ok: false, error: status.error };
+  const existing = publishedFor(status, publishedPort);
+  const target = targetFor(phonePort);
+  // An older version of this plugin pointed the published port at the console
+  // of this computer. That forwarding is ours as well, and it is moved to the
+  // phone side.
+  const legacy = targetFor(publishedPort);
+  if (existing && existing.TCPForward !== target && existing.TCPForward !== legacy) {
+    return { ok: false, error: `端口 ${publishedPort} 上已经有别的转发，没有动它。` };
+  }
+  const commands = existing && existing.TCPForward === target
+    ? []
+    : [['serve', '--bg', '--tcp=' + publishedPort, 'tcp://' + target]];
+  return { ok: true, commands, ready: true };
+}
+
+export async function applyForward(publishedPort, phonePort) {
+  const plan = await planForward(publishedPort, phonePort);
+  if (!plan.ok) return plan;
+  for (const command of plan.commands) {
+    const result = await call(command);
+    if (!result.ok) return { ok: false, error: result.error };
+  }
+  return { ok: true };
+}
+
+// Only a forwarding that points at this service is removed.
+export async function removeForward(publishedPort, phonePort) {
+  const status = await serveState();
+  const existing = status.ok ? publishedFor(status, publishedPort) : null;
+  const ours = existing && (
+    existing.TCPForward === targetFor(phonePort) ||
+    existing.TCPForward === targetFor(publishedPort)
+  );
+  if (!ours) {
+    return { ok: false, error: '没有找到属于这个插件的转发。' };
+  }
+  const result = await call(['serve', '--tcp=' + publishedPort, 'off']);
+  return result.ok ? { ok: true } : { ok: false, error: result.error };
+}