dsh-token-receipt 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,24 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+
5
+ ## Unreleased
6
+
7
+ - Add Japanese plugin metadata, sidebar and receipt translations, date formatting, and Japanese font fallbacks.
8
+ - Estimate model costs from the public models.dev catalogue, with a one-hour cache.
9
+ - Preserve provider/model identity and price input, cache reads, cache writes, and output separately.
10
+ - Use the DeepSeek Flash official reference rate and peak policy for WorkBuddy's deepseek-v4.1-flash route.
11
+ - Add model line amounts, cost breakdown, estimated total, and USD/CNY/JPY selection to the receipt.
12
+ - Default currency follows the interface language, with an explicit automatic mode and manual overrides.
13
+ - Convert JPY using a dated reference rate (2026-11-13: 1 USD = 160 JPY); preserve fractional-yen precision for small estimates.
14
+ - Mark missing prices, partial subtotals, stale prices, and the WorkBuddy reference-rate override.
15
+ - Keep the DSH whale logo and include monetary amounts and pricing notes in PNG/print output.
16
+
17
+ ## 1.0.0 — 2026-11-14
18
+
19
+ - Initial release.
20
+ - Daily, weekly, and monthly token usage bills.
21
+ - Receipt-printer animation with stepped paper feed, torn edge, and barcode.
22
+ - Save the receipt as a 3× PNG.
23
+ - Print / PDF action with a print-only stylesheet.
24
+ - Light/dark themes, Chinese/English UI, and reduced-motion support.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 maxlee
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,108 @@
1
- # Temporary Holding Version
1
+ # Token Receipt for DeepSeek Harness
2
2
 
3
- 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.
3
+ [![npm version](https://img.shields.io/npm/v/dsh-token-receipt.svg)](https://www.npmjs.com/package/dsh-token-receipt)
4
+ [![license](https://img.shields.io/npm/l/dsh-token-receipt.svg)](LICENSE)
5
+
6
+ A DeepSeek Harness plugin that prints your daily, weekly, or monthly token
7
+ usage as a tactile receipt — complete with a stepped paper feed, a torn edge,
8
+ and a barcode. Save the finished receipt as a PNG or send it through the
9
+ system print dialog. The receipt includes model costs and an estimated total.
10
+
11
+ [中文说明](README.zh.md)
12
+
13
+ ![Token Receipt in dark mode](docs/screenshots/dark.png)
14
+
15
+ ## Features
16
+
17
+ - **Daily / weekly / monthly bills** — switch periods and move backwards or
18
+ forwards without leaving the page.
19
+ - **Tactile receipt printer animation** — processing, stepped paper feed, and
20
+ a completion state, adapted from the dqnamo Receipt Printer study.
21
+ - **Estimated costs** — model line prices, four token cost categories, and a prominent total, using the public models.dev catalogue. The default currency follows the interface language (Chinese → CNY, English → USD, Japanese → JPY); choose USD, CNY or JPY manually at any time, or return to Follow language.
22
+ - **Save as PNG** — exports the actual receipt card at 3× resolution.
23
+ - **Print / PDF** — uses the browser's system print dialog with a print-only
24
+ stylesheet, so only the receipt is printed.
25
+ - **Local usage** — session data stays on your machine. Only the public price catalogue is fetched online; no usage or session text is uploaded.
26
+ - **Light and dark themes**, Chinese, English and Japanese, and reduced-motion support. Select **日本語** in DSH's language settings to use the Japanese interface.
27
+
28
+ ![Token Receipt in light mode](docs/screenshots/light.png)
29
+
30
+ ## Install
31
+
32
+ ### From npm (recommended)
33
+
34
+ Open **Plugins → Add plugin** in DeepSeek Harness and enter:
35
+
36
+ ```text
37
+ dsh-token-receipt
38
+ ```
39
+
40
+ Or use the DSH `plugin_manager` tool with an installation spec:
41
+
42
+ ```json
43
+ {
44
+ "action": "install_bundle",
45
+ "target": "dsh-token-receipt@1.0.0"
46
+ }
47
+ ```
48
+
49
+ After installation, open **Token 账单 / Token receipt** from the left sidebar.
50
+ If DSH reports `restart-required`, restart the app once.
51
+
52
+ ### From a local checkout
53
+
54
+ ```text
55
+ plugin_manager install_bundle
56
+ target: /absolute/path/to/dsh-token-receipt
57
+ ```
58
+
59
+ ## Usage
60
+
61
+ 1. Open **Token 账单 / Token receipt** in the left sidebar.
62
+ 2. Pick **日 / 周 / 月** (day / week / month), or use the date picker.
63
+ 3. The first visit plays the printer animation; use **重播打印 / Replay print**
64
+ to replay it.
65
+ 4. Use **保存 PNG / Save PNG** to download a high-resolution receipt image.
66
+ 5. Use **打印 / PDF / Print / PDF** for the system print dialog.
67
+
68
+ ![Monthly bill](docs/screenshots/light.png)
69
+
70
+ ## Data and privacy
71
+
72
+ The plugin reads token usage from local DSH session records through the DSH
73
+ host APIs. It does not send session data anywhere. Only messages with a
74
+ recorded `usage` value are included; old messages without usage metadata are
75
+ not estimated. Prices are fetched from https://models.dev/api.json and cached for one hour. Costs are reference estimates, not provider invoices; unavailable model prices are marked instead of treated as free.
76
+
77
+ See [Pricing](docs/PRICING.md) for the formula, provider matching, the WorkBuddy override, currency conversion, and pricing limits.
78
+
79
+ ## Compatibility
80
+
81
+ - DeepSeek Harness `>=0.2.2-rc.3 <0.3.0`
82
+ - Node.js `^22.19.0 || >=24.0.0`
83
+
84
+ The bundle contains both a Host half (`index.js`) and a Client half
85
+ (`client.js`), plus locale resources, a detail illustration, and an icon.
86
+
87
+ ## Development
88
+
89
+ ```bash
90
+ npm run check
91
+ npm test
92
+ npm pack --dry-run
93
+ ```
94
+
95
+ The plugin has no runtime npm dependencies. Fonts are embedded in the client
96
+ bundle: Inter and JetBrains Mono, both under the SIL Open Font License 1.1.
97
+ See [docs/FONTS.md](docs/FONTS.md).
98
+
99
+ ## Credits
100
+
101
+ The receipt-printer interaction is inspired by
102
+ [dqnamo's Receipt Printer experiment](https://www.dqnamo.com/experiments/receipt-printer).
103
+ This repository is an independent implementation; the bundled textures are
104
+ original procedural SVGs. Pricing resolution is adapted from [dsh-context](https://github.com/bowenliang123/dsh-context) under Apache-2.0; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
105
+
106
+ ## License
107
+
108
+ MIT for original code — see [LICENSE](LICENSE). Adapted pricing code retains its Apache-2.0 notices; bundled fonts retain their OFL licenses.
package/README.zh.md ADDED
@@ -0,0 +1,101 @@
1
+ # Token 账单 · DeepSeek Harness 插件
2
+
3
+ [![npm 版本](https://img.shields.io/npm/v/dsh-token-receipt.svg)](https://www.npmjs.com/package/dsh-token-receipt)
4
+ [![许可证](https://img.shields.io/npm/l/dsh-token-receipt.svg)](LICENSE)
5
+
6
+ 把日、周、月的 token 用量打印成一张有手感的小票:阶梯送纸、撕边、条形码,
7
+ 小票展示模型费用与预估总计,打印完成后可保存为 PNG,也可以走系统打印 / PDF。
8
+
9
+ [English](README.md)
10
+
11
+ ![深色主题下的 Token 账单](docs/screenshots/dark.png)
12
+
13
+ ## 功能
14
+
15
+ - **日 / 周 / 月账单**:同一个页面切换周期,向前或向后翻查。
16
+ - **小票打印机动画**:整理用量 → 阶梯送纸 → 打印完成,参考 dqnamo 的
17
+ Receipt Printer 实验。
18
+ - **预估费用**:按模型及输入、输出、缓存读写分别计费,突出显示总价。默认币种跟随语言(中文 CNY、英文 USD、日文 JPY),也可手动切换 USD/CNY/JPY,或恢复「跟随语言」。
19
+ - **保存 PNG**:按 3 倍分辨率导出当前小票图片。
20
+ - **打印 / PDF**:调用系统打印对话框,打印样式只输出小票。
21
+ - **只读本地数据**:从本机 DSH 会话记录读取 token 用量,不会发送到任何地方。
22
+ - 支持浅色 / 深色主题、中/英/日文界面和 reduced-motion;在 DSH 语言设置中选择「日本語」即可使用日文。
23
+
24
+ ![浅色主题下的 Token 账单](docs/screenshots/light.png)
25
+
26
+ ## 安装
27
+
28
+ ### 从 npm 安装(推荐)
29
+
30
+ 在 DeepSeek Harness 中打开 **Plugins → Add plugin**,输入:
31
+
32
+ ```text
33
+ dsh-token-receipt
34
+ ```
35
+
36
+ 也可以使用 DSH 的 `plugin_manager` 工具:
37
+
38
+ ```json
39
+ {
40
+ "action": "install_bundle",
41
+ "target": "dsh-token-receipt@1.0.0"
42
+ }
43
+ ```
44
+
45
+ 安装后,在左侧栏打开「Token 账单」。如果 DSH 提示 `restart-required`,
46
+ 重启一次应用即可。
47
+
48
+ ### 从本地目录安装
49
+
50
+ ```text
51
+ plugin_manager install_bundle
52
+ target: /absolute/path/to/dsh-token-receipt
53
+ ```
54
+
55
+ ## 使用
56
+
57
+ 1. 左侧栏打开「Token 账单」。
58
+ 2. 选择 **日 / 周 / 月**,或点日期选择器跳到某一天。
59
+ 3. 第一次打开会自动播放一次打印动画;点「重播打印」可再次播放。
60
+ 4. 「保存 PNG」会把高分辨率小票下载到本地。
61
+ 5. 「打印 / PDF」会打开系统打印对话框。
62
+
63
+ ![月账单](docs/screenshots/light.png)
64
+
65
+ ## 数据与隐私
66
+
67
+ 插件通过 DSH 的本地会话记录读取 token 用量,不发送任何会话数据;只统计
68
+ 记录了 `usage` 的消息,不会估算没有 usage 元数据的旧消息。联网仅获取
69
+ https://models.dev/api.json 的公开价格,缓存一小时,不上传会话或用量数据。
70
+ 金额为参考估算,不等同于供应商实付账单;缺价模型会明确标记。
71
+
72
+ 计费公式、模型匹配、WorkBuddy 官方参考价回退和币种规则见 [计价说明](docs/PRICING.md)。
73
+
74
+ ## 兼容性
75
+
76
+ - DeepSeek Harness `>=0.2.2-rc.3 <0.3.0`
77
+ - Node.js `^22.19.0 || >=24.0.0`
78
+
79
+ ## 开发
80
+
81
+ ```bash
82
+ npm run check
83
+ npm test
84
+ npm pack --dry-run
85
+ ```
86
+
87
+ 插件没有运行时 npm 依赖。字体以 base64 内嵌在客户端 bundle 中:
88
+ Inter 与 JetBrains Mono,均为 SIL Open Font License 1.1,详见
89
+ [docs/FONTS.md](docs/FONTS.md)。
90
+
91
+ ## 致谢
92
+
93
+ 小票打印机的交互参考了
94
+ [dqnamo Receipt Printer](https://www.dqnamo.com/experiments/receipt-printer);
95
+ 内置纹理由程序化 SVG 生成。价格匹配参考
96
+ [dsh-context](https://github.com/bowenliang123/dsh-context),保留 Apache-2.0 授权,
97
+ 详见 [第三方说明](THIRD_PARTY_NOTICES.md)。
98
+
99
+ ## 许可证
100
+
101
+ 原创代码采用 MIT,详见 [LICENSE](LICENSE)。适配的价格匹配代码保留 Apache-2.0 说明;内嵌字体保留 OFL 授权。
package/RELEASING.md ADDED
@@ -0,0 +1,31 @@
1
+ # Releasing
2
+
3
+ This repository is set up for a public npm package and a GitHub repository.
4
+
5
+ ## Before the first publish
6
+
7
+ 1. Confirm the package name in `package.json` is still available:
8
+ `npm view dsh-token-receipt version`.
9
+ 2. Log in to npm with the account that owns `@maxlee`:
10
+ `npm login`.
11
+ 3. Run the local checks:
12
+ `npm run check && npm pack --dry-run`.
13
+
14
+ ## Publish a version
15
+
16
+ ```bash
17
+ npm version patch # or minor / major
18
+ git push origin main --tags
19
+ npm publish --access public
20
+ ```
21
+
22
+ For a trusted-publishing release from GitHub Actions, create an
23
+ `NPM_TOKEN` repository secret (or configure npm trusted publishing) and push a
24
+ `v*` tag. The `release.yml` workflow publishes with provenance.
25
+
26
+ ## Push the repository
27
+
28
+ ```bash
29
+ git remote add origin git@github.com:maxlee/dsh-token-receipt.git
30
+ git push -u origin main --tags
31
+ ```
@@ -0,0 +1,36 @@
1
+ # Third-party notices
2
+
3
+ ## dsh-context
4
+
5
+ Parts of `pricing.js` are adapted from the following files in
6
+ [dsh-context](https://github.com/bowenliang123/dsh-context), commit
7
+ `d81325ec6bab9dae9bf83e7a866ac74119504e18`:
8
+
9
+ - `src/shared/pricing.ts`
10
+ - `src/shared/priceIdentity.ts`
11
+ - `src/shared/providers.ts`
12
+
13
+ Copyright 2025 bowenliang123.
14
+
15
+ These portions are licensed under the Apache License, Version 2.0. A complete
16
+ copy of the upstream license, including its copyright notice, is provided in
17
+ [`licenses/dsh-context-LICENSE.txt`](licenses/dsh-context-LICENSE.txt).
18
+ The upstream repository did not contain a separate NOTICE file at that commit.
19
+
20
+ The adapted file prominently records its modifications: the TypeScript
21
+ resolver was converted to a self-contained JavaScript module; Token Receipt
22
+ adds an activation-scoped price catalog, an explicit user-requested WorkBuddy
23
+ Flash reference-price override, per-message peak/off-peak pricing, and USD
24
+ amount breakdowns. The override is marked `user-override` in API responses.
25
+
26
+ The rest of Token Receipt remains under the repository's MIT license. These
27
+ notices do not change the license of the upstream portions.
28
+
29
+ ## Model price data
30
+
31
+ Reference model rates are fetched at runtime from
32
+ [models.dev](https://models.dev/api.json). The model directory and its data
33
+ sources are maintained by [models.dev](https://github.com/anomalyco/models.dev).
34
+ The plugin does not bundle a copied model catalogue. Rates are reference
35
+ estimates and may differ from invoices, subscription entitlements, and
36
+ provider-specific pricing conditions.
@@ -0,0 +1,10 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="360" height="520" viewBox="0 0 360 520">
2
+ <filter id="paper-grain" x="-10%" y="-10%" width="120%" height="120%" color-interpolation-filters="sRGB">
3
+ <feTurbulence type="fractalNoise" baseFrequency="0.012 0.02" numOctaves="3" seed="42" stitchTiles="stitch" />
4
+ <feColorMatrix type="saturate" values="0" />
5
+ <feComponentTransfer>
6
+ <feFuncA type="table" tableValues="0 0.22" />
7
+ </feComponentTransfer>
8
+ </filter>
9
+ <rect width="100%" height="100%" filter="url(#paper-grain)" opacity="0.35" />
10
+ </svg>
@@ -0,0 +1,10 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="180" height="180" viewBox="0 0 180 180">
2
+ <filter id="plastic-grain" x="-10%" y="-10%" width="120%" height="120%" color-interpolation-filters="sRGB">
3
+ <feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="9" stitchTiles="stitch" />
4
+ <feColorMatrix type="saturate" values="0" />
5
+ <feComponentTransfer>
6
+ <feFuncA type="table" tableValues="0 0.18" />
7
+ </feComponentTransfer>
8
+ </filter>
9
+ <rect width="100%" height="100%" filter="url(#plastic-grain)" opacity="0.55" />
10
+ </svg>