bitbank-lab-mcp 0.4.1 → 0.5.1

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.
Files changed (61) hide show
  1. package/README.md +8 -7
  2. package/lib/calendar.ts +266 -0
  3. package/lib/datetime.ts +62 -0
  4. package/lib/http.ts +103 -4
  5. package/lib/pairs.ts +58 -0
  6. package/lib/pattern-diagrams.ts +118 -45
  7. package/lib/tx-archive.ts +34 -20
  8. package/lib/tx-fetch.ts +732 -0
  9. package/package.json +7 -6
  10. package/src/handlers/analyzeMyPortfolioHandler.ts +1267 -161
  11. package/src/handlers/detectPatternsHandler.ts +69 -12
  12. package/src/handlers/detectPatternsViewsHandler.ts +969 -102
  13. package/src/handlers/getVolatilityMetricsHandler.ts +2 -2
  14. package/src/handlers/portfolio/calc.ts +1211 -127
  15. package/src/handlers/portfolio/calendar.ts +43 -0
  16. package/src/handlers/portfolio/fetch.ts +342 -4
  17. package/src/handlers/portfolio/types.ts +414 -18
  18. package/src/mcp-apps-hydration.ts +191 -0
  19. package/src/private/elicitation.ts +48 -7
  20. package/src/private/schemas.ts +700 -41
  21. package/src/prompts/intermediate.ts +28 -0
  22. package/src/schema/analysis.ts +64 -4
  23. package/src/schema/base.ts +111 -6
  24. package/src/schema/candle-validate.ts +5 -1
  25. package/src/schema/market-data.ts +126 -21
  26. package/src/schema/patterns.ts +868 -28
  27. package/tools/analyze_candle_patterns.ts +17 -5
  28. package/tools/analyze_market_signal.ts +19 -7
  29. package/tools/analyze_volume_profile.ts +170 -113
  30. package/tools/detect_patterns.ts +277 -55
  31. package/tools/get_candles.ts +226 -173
  32. package/tools/get_flow_metrics.ts +400 -262
  33. package/tools/get_transactions.ts +126 -33
  34. package/tools/patterns/bar-thresholds.ts +130 -0
  35. package/tools/patterns/candidate-filter.ts +106 -0
  36. package/tools/patterns/config.ts +475 -30
  37. package/tools/patterns/detect_doubles.ts +933 -354
  38. package/tools/patterns/detect_hs.ts +1636 -235
  39. package/tools/patterns/detect_pennants.ts +45 -16
  40. package/tools/patterns/detect_triangles.ts +158 -20
  41. package/tools/patterns/detect_triples.ts +1252 -178
  42. package/tools/patterns/detect_wedges.ts +178 -45
  43. package/tools/patterns/helpers.ts +132 -125
  44. package/tools/patterns/min-bars.ts +127 -0
  45. package/tools/patterns/mutual-exclusion.ts +199 -0
  46. package/tools/patterns/period.ts +119 -0
  47. package/tools/patterns/ranking.ts +11 -2
  48. package/tools/patterns/reversal-gate.ts +205 -0
  49. package/tools/patterns/scan-window.ts +169 -0
  50. package/tools/patterns/scoring.ts +73 -0
  51. package/tools/patterns/structural.ts +1227 -3
  52. package/tools/patterns/swing.ts +44 -4
  53. package/tools/patterns/target-confounders.ts +171 -0
  54. package/tools/patterns/target-reach.ts +551 -0
  55. package/tools/patterns/types.ts +146 -1
  56. package/tools/private/analyze_my_portfolio.ts +1 -1
  57. package/tools/private/preview_cancel_order.ts +46 -7
  58. package/tools/trading_process/lib/fetch_candles.ts +18 -8
  59. package/tsconfig.json +2 -2
  60. package/ui/cancel-confirm/dist/cancel-confirm.html +30 -30
  61. package/ui/order-confirm/dist/order-confirm.html +44 -44
package/README.md CHANGED
@@ -115,7 +115,9 @@ nvm/volta などのバージョン管理ツールをお使いの方には特に
115
115
 
116
116
  **C. 取引注文・注文キャンセル実行(要 API キー):**
117
117
 
118
- B に加えて、対応ホスト上での発注・注文キャンセルまで実行。実行前に必ず確認ステップ(preview → ユーザーの明示確認)が入ります。
118
+ B に加えて、発注・注文キャンセルまで実行。実行前に必ず確認ステップ(preview → ユーザーの明示確認)が入ります。
119
+
120
+ Claude Desktop では確認カードのボタンから実行するため、B の設定に **`BITBANK_MCP_APPS_EXECUTE=1` を追加**してオプトインします(**既定は無効**。設定する前に下の「⚠️ `BITBANK_MCP_APPS_EXECUTE=1` を設定する前に読んでください」を確認してください)。
119
121
 
120
122
  ```json
121
123
  {
@@ -125,7 +127,8 @@ B に加えて、対応ホスト上での発注・注文キャンセルまで実
125
127
  "args": ["-y", "bitbank-lab-mcp"],
126
128
  "env": {
127
129
  "BITBANK_API_KEY": "your_api_key",
128
- "BITBANK_API_SECRET": "your_api_secret"
130
+ "BITBANK_API_SECRET": "your_api_secret",
131
+ "BITBANK_MCP_APPS_EXECUTE": "1"
129
132
  }
130
133
  }
131
134
  }
@@ -136,7 +139,7 @@ B に加えて、対応ホスト上での発注・注文キャンセルまで実
136
139
  >
137
140
  > ※ **「出金」権限は有効化しないことを強く推奨します**。本サーバーは出金系ツール未実装のため不要です。
138
141
 
139
- 発注・取消の実行には**ユーザーの明示確認が必須**です。確認トークンは `content` / `structuredContent` に載らないため、LLM が preview 応答から直接 execute することはできません。旧 `BITBANK_TRUST_HOST_APPROVAL` オプトイン(iframe に token を `structuredContent` で載せる妥協モード)はセキュリティ上撤去済みで、設定しても無視されます。
142
+ 発注・取消の実行には**ユーザーの明示確認が必須**です。確認トークンは `content` / `structuredContent` には載りません。`BITBANK_MCP_APPS_EXECUTE=1` を設定し、かつクライアントが elicitation 非対応で MCP Apps UI を宣言している場合(Claude Desktop 等)に限り、確認カードに渡すためツール結果の `_meta` に載ります。この場合の安全性は「ホストが `_meta` を LLM に渡さない」ことに依存し、仕様上の保証はありません(下の「⚠️ `BITBANK_MCP_APPS_EXECUTE=1` を設定する前に読んでください」)。
140
143
 
141
144
  確認の経路はクライアントによって変わります。
142
145
 
@@ -154,8 +157,6 @@ B に加えて、対応ホスト上での発注・注文キャンセルまで実
154
157
  * **仕様上の保証ではありません。** MCP Apps 仕様の該当記述は "Best Practices" の箇条書きで、MUST / SHOULD を伴いません。適合要件ではなく意図の説明です
155
158
  * **ホストのアップデートで壊れても、サーバー側では検知できません。** ホストが `_meta` をモデルコンテキストに含めるようになった瞬間に前提は崩れますが、その変化はサーバーから観測できません。**壊れ方は静かです**
156
159
  * この領域は実装が流動的です(`structuredContent` の喪失回帰など、関連トラッカーに 2026-05〜08 の issue が複数)
157
- * **クライアントの申告は検証できません。** トークンを渡す条件は「クライアントが MCP Apps UI 対応を宣言していること」ですが、これはクライアント側の自己申告で、サーバーは真偽を判定できません。確認カードを描画しないクライアントでも、宣言さえすればトークンを取得できます。**信頼できるクライアントでのみ有効にしてください**
158
- * **API キーの置き場所で意味が変わります。** キーをクライアント側(`claude_desktop_config.json` の `env` 等)に設定している場合、クライアントは既にキーを保持しているため、このフラグによる追加のリスクはありません。**サーバー側の `.env` に置く構成では、クライアントに本来無い実行権限を与えることになります**。この構成での有効化は推奨しません
159
160
 
160
161
  万一トークンが漏れた場合でも、被害は **「直前にプレビューした注文 1 件(一括取消ならプレビュー済みの注文 ID 集合 1 セット)が、60 秒以内に 1 回だけ実行される」** に限定されます。トークンは注文内容に HMAC で束縛されており、攻撃者が金額・数量・ペア・方向を選ぶことはできません。
161
162
 
@@ -268,7 +269,7 @@ Claude Desktop の UI に表示される名前は `claude_desktop_config.json`
268
269
  }
269
270
  ```
270
271
 
271
- API キーが不要な場合は `env` ブロックごと削除して OK。セクション 1 の A〜C と同様に、取引実行まで使う場合は確認フローに対応したクライアントが必要です(旧 `BITBANK_TRUST_HOST_APPROVAL` は不要・無効です)。
272
+ API キーが不要な場合は `env` ブロックごと削除して OK。セクション 1 の A〜C と同様に、取引実行まで使う場合は確認フローに対応したクライアントが必要です。
272
273
 
273
274
  #### Claude Code(CLI から登録する場合)
274
275
 
@@ -444,7 +445,7 @@ npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp
444
445
  ```
445
446
  ソースコードから動かす場合は `npx @modelcontextprotocol/inspector -- tsx src/server.ts`([開発者向け](#開発者向けソースから起動) を参照)。
446
447
 
447
- **Q. 当日の約定(フロー)データが少ない・古い時間帯が取れない** bitbank 側の仕様です。約定履歴の日付アーカイブ(`/transactions/{YYYYMMDD}`)は **UTC 暦日単位**で、当該 UTC 日の完了後(日本時間 9:00 以降、さらに公開遅延あり)にのみ公開されます。進行中の UTC 日の約定は直近約 60 件(latest)しか取得できないため、`get_flow_metrics` 等では当日区間のカバレッジが限定的になります(結果に warning として明示されます)。ローソク足(`get_candles`)は進行中の UTC 日でもリアルタイムで取得できます。
448
+ **Q. 当日の約定(フロー)データが少ない・古い時間帯が取れない** bitbank 側の仕様です。約定履歴の日付アーカイブ(`/transactions/{YYYYMMDD}`)は **UTC 暦日単位**で、当該 UTC 日の完了後(日本時間 9:00 以降、さらに公開遅延あり)にのみ公開されます。進行中の UTC 日の約定は直近約 60 件(latest)しか取得できないため、`get_flow_metrics` 等では当日区間のカバレッジが限定的になります(結果に warning として明示されます)。ローソク足(`get_candles`)は進行中の UTC 日でもリアルタイムで取得できます。<br>なお**公開済みの過去区間**であれば、`get_flow_metrics` / `analyze_volume_profile` の `since` / `until`(オフセット付き ISO8601、最大 7 日)でその区間の**全件**を集計できます(例: `since=2026-08-01T00:00:00Z`, `until=2026-08-02T00:00:00Z` で UTC 8/1 の 1 日ぶん)。件数上限による切り捨ては起きません。
448
449
 
449
450
  ## トラブルシューティング
450
451
 
@@ -0,0 +1,266 @@
1
+ /**
2
+ * 暦日(カレンダーデー)プリミティブ。
3
+ *
4
+ * 「ある tz の暦日はいつ始まっていつ終わるか」「その瞬間はどの暦日キーか」
5
+ * 「2 時刻の間にどの暦日キーが挟まるか」「その暦日はもう完了したか」だけを扱う。
6
+ * 上流 API の仕様(bitbank の約定アーカイブは UTC 暦日単位、/candlestick は UTC 暦日
7
+ * chunk 等)はドメイン層(`lib/tx-archive.ts` など)の責務であり、本モジュールは持たない。
8
+ *
9
+ * ## tz は必ず明示引数で渡す
10
+ *
11
+ * 既定値を置かない。同じ関数名で暦の基準が呼び出し箇所ごとに違う——現に
12
+ * `date: 'YYYYMMDD'` の解釈が UTC 暦日と JST 暦日に割れている——という問題を
13
+ * lib 側に持ち込まないため。`'UTC'` も普通の tz として渡す。
14
+ *
15
+ * ## 入力が不正なときの挙動
16
+ *
17
+ * - **tz が不正 / ms が非有限** → `TypeError` を throw する。呼び出し側のバグであり、
18
+ * 黙って `NaN` や `'Invalid Date'` を伝播させると原因の遠い場所で壊れる。
19
+ * ユーザー入力の tz は `isSupportedTimeZone()` で先に正規化すること。
20
+ * - **キー文字列の形式不正 / 実在しない日付** → `null`(`parse*`)または `false`(`is*`)を返す。
21
+ * こちらはユーザー入力由来なので throw しない。
22
+ *
23
+ * 素の `Date` コンストラクタは banned(`.claude/hooks/post-ts-lint.sh`)。日時計算は
24
+ * `lib/datetime.ts` の dayjs(utc / timezone / customParseFormat プラグイン適用済み)に集約する。
25
+ */
26
+
27
+ import { dayjs } from './datetime.js';
28
+
29
+ /** 暦日キーの形式(YYYYMMDD)。実在日かどうかは見ない。 */
30
+ const DAY_KEY_PATTERN = /^\d{8}$/;
31
+
32
+ /** 暦年キーの形式(YYYY)。 */
33
+ const YEAR_KEY_PATTERN = /^\d{4}$/;
34
+
35
+ /** 暦日キー(`YYYYMMDD`)。文字列の辞書順が時系列順と一致する。 */
36
+ export type DayKey = string;
37
+
38
+ /** 暦年キー(`YYYY`)。 */
39
+ export type YearKey = string;
40
+
41
+ /** 暦上の 1 区間。 */
42
+ export interface CalendarSpan {
43
+ /** 区間の最初のミリ秒。 */
44
+ readonly startMs: number;
45
+ /** 区間の最後のミリ秒(**inclusive**)。次の区間の開始 - 1 に等しい。 */
46
+ readonly endMs: number;
47
+ }
48
+
49
+ /**
50
+ * dayjs(= Intl)が解釈できる tz 文字列か。空文字・未定義・不正な IANA 名は false。
51
+ *
52
+ * 不正 tz を既定値へ倒すかどうかは呼び出し側のポリシーなので、本モジュールでは判定だけ提供する。
53
+ * 例: `const safeTz = isSupportedTimeZone(tz) ? tz : 'Asia/Tokyo';`
54
+ */
55
+ export function isSupportedTimeZone(tz: unknown): tz is string {
56
+ if (typeof tz !== 'string' || tz.length === 0) return false;
57
+ try {
58
+ return dayjs(0).tz(tz).isValid();
59
+ } catch {
60
+ // Intl は不正な tz 名に RangeError を投げる
61
+ return false;
62
+ }
63
+ }
64
+
65
+ function assertTimeZone(tz: string): void {
66
+ if (!isSupportedTimeZone(tz)) {
67
+ throw new TypeError(`calendar: unsupported time zone (received: ${String(tz)})`);
68
+ }
69
+ }
70
+
71
+ function assertFiniteMs(ms: number, label: string): void {
72
+ if (typeof ms !== 'number' || !Number.isFinite(ms)) {
73
+ throw new TypeError(`calendar: ${label} must be a finite epoch millisecond value (received: ${String(ms)})`);
74
+ }
75
+ }
76
+
77
+ function inTz(ms: number, tz: string, label = 'ms'): dayjs.Dayjs {
78
+ assertFiniteMs(ms, label);
79
+ assertTimeZone(tz);
80
+ return dayjs(ms).tz(tz);
81
+ }
82
+
83
+ /**
84
+ * ms が属する tz 暦日の最初のミリ秒。
85
+ *
86
+ * DST 開始が 00:00 の tz(例: 2017-10-15 の America/Sao_Paulo は 00:00 が存在しない)では
87
+ * その暦日に実在する最初の瞬間(01:00)を返す。
88
+ */
89
+ export function startOfDayMs(ms: number, tz: string): number {
90
+ return inTz(ms, tz).startOf('day').valueOf();
91
+ }
92
+
93
+ /** ms が属する tz 暦日の最後のミリ秒(23:59:59.999 相当。**inclusive**)。 */
94
+ export function endOfDayMs(ms: number, tz: string): number {
95
+ return inTz(ms, tz).endOf('day').valueOf();
96
+ }
97
+
98
+ /** ms が属する tz 暦年の最初のミリ秒(1/1 00:00:00.000 in tz)。 */
99
+ export function startOfYearMs(ms: number, tz: string): number {
100
+ return inTz(ms, tz).startOf('year').valueOf();
101
+ }
102
+
103
+ /** ms が属する tz 暦年の最後のミリ秒(12/31 23:59:59.999 in tz。**inclusive**)。 */
104
+ export function endOfYearMs(ms: number, tz: string): number {
105
+ return inTz(ms, tz).endOf('year').valueOf();
106
+ }
107
+
108
+ /** ms が属する tz 暦日のキー(`YYYYMMDD`)。 */
109
+ export function toDayKey(ms: number, tz: string): DayKey {
110
+ return inTz(ms, tz).format('YYYYMMDD');
111
+ }
112
+
113
+ /** ms が属する tz 暦年のキー(`YYYY`)。 */
114
+ export function toYearKey(ms: number, tz: string): YearKey {
115
+ return inTz(ms, tz).format('YYYY');
116
+ }
117
+
118
+ /**
119
+ * `YYYYMMDD` の**形式**を満たすか。2026-02-30 のような実在しない日付も true になる。
120
+ * 実在日まで確かめたい場合は `parseDayKey()` が `null` を返すかで判定する。
121
+ */
122
+ export function isDayKeyFormat(value: unknown): value is DayKey {
123
+ return typeof value === 'string' && DAY_KEY_PATTERN.test(value);
124
+ }
125
+
126
+ /** `YYYY` の形式を満たすか。 */
127
+ export function isYearKeyFormat(value: unknown): value is YearKey {
128
+ return typeof value === 'string' && YEAR_KEY_PATTERN.test(value);
129
+ }
130
+
131
+ /**
132
+ * 暦日キー(`YYYYMMDD`)を tz 上の区間に変換する。形式不正・実在しない日付は `null`。
133
+ *
134
+ * `dayjs.tz('2026-02-30', tz)` は例外を投げずに 3/2 へ繰り上げてしまうため、
135
+ * tz を当てる前に UTC の strict parse で実在日かどうかを確かめる。
136
+ */
137
+ export function parseDayKey(key: string, tz: string): CalendarSpan | null {
138
+ if (!isDayKeyFormat(key)) return null;
139
+ if (!dayjs.utc(key, 'YYYYMMDD', true).isValid()) return null;
140
+ assertTimeZone(tz);
141
+ const d = dayjs.tz(`${key.slice(0, 4)}-${key.slice(4, 6)}-${key.slice(6, 8)}`, tz);
142
+ if (!d.isValid()) return null;
143
+ return { startMs: d.startOf('day').valueOf(), endMs: d.endOf('day').valueOf() };
144
+ }
145
+
146
+ /**
147
+ * 暦日キーを tz 上の区間に変換する(**繰り上げ許容**版)。
148
+ *
149
+ * `parseDayKey` が実在しない日付を `null` で弾くのに対し、こちらはグレゴリオ暦の繰り上げで
150
+ * 解釈する(`20260230` → 2026-03-02、`20251232` → 2026-01-01)。形式不正は `null`。
151
+ *
152
+ * 入力の**形式だけ**を検証して実在日を見ない層を通った値を扱う呼び出し側のための入口。
153
+ * 現に `lib/validate.ts` の `validateDate` は `/^\d{8}$/` しか見ず、`get_candles` の `date` は
154
+ * 繰り上げ解釈のまま anchor と fetch 範囲を組んでいる。厳密解釈へ倒すと「anchor 無効 →
155
+ * 最新側 limit 本」のように結果が silent に変わるため、繰り上げるかどうかは
156
+ * **呼び出し側が関数の選択として明示する**。
157
+ *
158
+ * 既定は `parseDayKey`(実在日を要求する方)を使うこと。
159
+ */
160
+ export function parseDayKeyAllowingOverflow(key: string, tz: string): CalendarSpan | null {
161
+ if (!isDayKeyFormat(key)) return null;
162
+ assertTimeZone(tz);
163
+ const d = dayjs.tz(`${key.slice(0, 4)}-${key.slice(4, 6)}-${key.slice(6, 8)}`, tz);
164
+ if (!d.isValid()) return null;
165
+ return { startMs: d.startOf('day').valueOf(), endMs: d.endOf('day').valueOf() };
166
+ }
167
+
168
+ /** 暦年キー(`YYYY`)を tz 上の区間に変換する。形式不正は `null`。 */
169
+ export function parseYearKey(key: string, tz: string): CalendarSpan | null {
170
+ if (!isYearKeyFormat(key)) return null;
171
+ assertTimeZone(tz);
172
+ const d = dayjs.tz(`${key}-01-01`, tz);
173
+ if (!d.isValid()) return null;
174
+ return { startMs: d.startOf('year').valueOf(), endMs: d.endOf('year').valueOf() };
175
+ }
176
+
177
+ /**
178
+ * 暦日キーを days 日ずらす。形式不正・実在しない日付・非整数 days は `null`。
179
+ *
180
+ * グレゴリオ暦の日付演算のみで、tz には依存しない(`20260301` の前日は
181
+ * どの tz でも `20260228` / 閏年なら `20260229`)。ミリ秒に落とさないので
182
+ * DST による 23h / 25h の日を跨いでもズレない。
183
+ */
184
+ export function shiftDayKey(key: string, days: number): DayKey | null {
185
+ if (!isDayKeyFormat(key) || !Number.isInteger(days)) return null;
186
+ const d = dayjs.utc(key, 'YYYYMMDD', true);
187
+ if (!d.isValid()) return null;
188
+ return d.add(days, 'day').format('YYYYMMDD');
189
+ }
190
+
191
+ /**
192
+ * [startMs, endMs] と交差する tz 暦日キーを昇順(inclusive)で列挙する。
193
+ * `startMs > endMs` なら空配列。
194
+ *
195
+ * 列挙はキーの日付演算で進めるため、DST で 23h / 25h になる日や月末・閏日を跨いでも
196
+ * 日が飛んだり重複したりしない。
197
+ */
198
+ export function enumerateDayKeys(startMs: number, endMs: number, tz: string): DayKey[] {
199
+ assertFiniteMs(startMs, 'startMs');
200
+ assertFiniteMs(endMs, 'endMs');
201
+ assertTimeZone(tz);
202
+ if (startMs > endMs) return [];
203
+ const lastKey = toDayKey(endMs, tz);
204
+ const keys: DayKey[] = [];
205
+ let key: DayKey | null = toDayKey(startMs, tz);
206
+ while (key != null && key <= lastKey) {
207
+ keys.push(key);
208
+ key = shiftDayKey(key, 1);
209
+ }
210
+ return keys;
211
+ }
212
+
213
+ /**
214
+ * 2 つの瞬間が属する tz 暦日の差(`toMs` の暦日 − `fromMs` の暦日、単位: 日)。
215
+ * 同じ暦日なら 0、`toMs` が翌日なら 1、前日なら -1。
216
+ *
217
+ * ミリ秒差を 86400000 で割ってはいけない。DST を挟むと 23h / 25h の日が出て 1 日ぶんずれる
218
+ * (`America/New_York` の 2025-01-01 → 06-16 は暦日で 166 日だが ms 差は 165 日 23 時間)。
219
+ * 暦日キーの日付演算で数えるためオフセットの変化に影響されない。
220
+ */
221
+ export function diffCalendarDays(fromMs: number, toMs: number, tz: string): number {
222
+ const from = dayjs.utc(toDayKey(fromMs, tz), 'YYYYMMDD', true);
223
+ const to = dayjs.utc(toDayKey(toMs, tz), 'YYYYMMDD', true);
224
+ return to.diff(from, 'day');
225
+ }
226
+
227
+ /**
228
+ * [startMs, endMs] と交差する tz 暦年キーを昇順(inclusive)で列挙する。
229
+ * `startMs > endMs` なら空配列。
230
+ */
231
+ export function enumerateYearKeys(startMs: number, endMs: number, tz: string): YearKey[] {
232
+ assertFiniteMs(startMs, 'startMs');
233
+ assertFiniteMs(endMs, 'endMs');
234
+ assertTimeZone(tz);
235
+ if (startMs > endMs) return [];
236
+ const firstYear = Number(toYearKey(startMs, tz));
237
+ const lastYear = Number(toYearKey(endMs, tz));
238
+ const keys: YearKey[] = [];
239
+ for (let y = firstYear; y <= lastYear; y++) keys.push(String(y).padStart(4, '0'));
240
+ return keys;
241
+ }
242
+
243
+ /**
244
+ * その暦日キーが nowMs 時点で**完了しているか**(= nowMs が属する暦日より前か)。
245
+ * 進行中の暦日・未来の暦日は false。形式不正も false。
246
+ */
247
+ export function isDayKeyCompleted(key: string, nowMs: number, tz: string): boolean {
248
+ if (!isDayKeyFormat(key)) return false;
249
+ return key < toDayKey(nowMs, tz);
250
+ }
251
+
252
+ /**
253
+ * 直近 count 個の完了済み tz 暦日キーを新しい順で返す。
254
+ * nowMs が属する進行中の暦日は含めない。count <= 0 / 非数値は空配列。
255
+ */
256
+ export function recentCompletedDayKeys(count: number, nowMs: number, tz: string): DayKey[] {
257
+ const wanted = Math.max(0, Math.floor(count));
258
+ if (!(wanted > 0)) return [];
259
+ const keys: DayKey[] = [];
260
+ let key = shiftDayKey(toDayKey(nowMs, tz), -1);
261
+ while (key != null && keys.length < wanted) {
262
+ keys.push(key);
263
+ key = shiftDayKey(key, -1);
264
+ }
265
+ return keys;
266
+ }
package/lib/datetime.ts CHANGED
@@ -35,6 +35,27 @@ export function toIsoMs(ms: number | null): string | null {
35
35
  return d.isValid() ? d.toISOString() : null;
36
36
  }
37
37
 
38
+ /**
39
+ * tz 文字列を「実際に整形に使える IANA タイムゾーン」へ正規化する。
40
+ *
41
+ * 空文字・未指定に加えて、**IANA 名として解決できない値**('Tokyo' / 'Not/AZone' 等)も
42
+ * `Asia/Tokyo` に畳む。`formatDateInTz` / `toIsoWithTz` は解決できない tz に対して
43
+ * `null` を返すだけなので、呼び出し側がそのまま使うと「表示行が丸ごと消える」
44
+ * 「日付が空文字になる」という形で情報が黙って落ちる。表示前にここを通すこと。
45
+ *
46
+ * 判定は固定 epoch(0)で行うので現在時刻に依存しない。
47
+ *
48
+ * @returns 解決できた tz、できなければ 'Asia/Tokyo'
49
+ */
50
+ export function resolveTz(tz: string | undefined | null, fallback: string = 'Asia/Tokyo'): string {
51
+ if (typeof tz !== 'string' || tz.length === 0) return fallback;
52
+ try {
53
+ return dayjs(0).tz(tz).isValid() ? tz : fallback;
54
+ } catch {
55
+ return fallback;
56
+ }
57
+ }
58
+
38
59
  /**
39
60
  * タイムスタンプをタイムゾーン付きISO風形式に変換
40
61
  * @param ts ミリ秒タイムスタンプ
@@ -161,6 +182,47 @@ export function parseIso8601(value: string): dayjs.Dayjs | null {
161
182
  return null;
162
183
  }
163
184
 
185
+ /**
186
+ * 日足未満(intraday)の時間足。
187
+ * 暦日だけで表示すると足の位置が特定できず「直近◯時間がスキャンされていない」という
188
+ * 誤読を招く(issue #200 の誤読の直接原因)ため、これらは時刻まで表示する。
189
+ *
190
+ * issue #233: 元は `tools/patterns/period.ts` にあったが、`lib/pattern-diagrams.ts`
191
+ * (構造図)からも必要になったため `lib/` へ移した。`lib/` → `tools/` の逆方向依存を
192
+ * 作らないための移動で、時間足の分類という土台的な判定は `lib/` 側が定位置。
193
+ * `tools/patterns/period.ts` は互換のため re-export している。
194
+ */
195
+ const INTRADAY_TYPES = new Set(['1min', '5min', '15min', '30min', '1hour', '4hour', '8hour', '12hour']);
196
+
197
+ /** 時間足が日足未満(= 表示に時刻まで含めるべき)か。 */
198
+ export function isIntradayType(type: string): boolean {
199
+ return INTRADAY_TYPES.has(type);
200
+ }
201
+
202
+ /**
203
+ * UTC ISO 文字列を、時間足に応じて暦日 `YYYY-MM-DD`(日足以上)または分単位
204
+ * `YYYY-MM-DD HH:mm`(intraday)へ整形する(issue #200 要件 F-1 の共通実装)。
205
+ *
206
+ * **暦日に潰すと intraday では 24 本が同じラベルになり、どの足かを特定できない。**
207
+ * `detect_patterns` の `content` はブレイク足・構成点・ターゲット初到達といった
208
+ * 「どの足か」が意味を持つ行を出すので、時間足を見て粒度を切り替える必要がある。
209
+ *
210
+ * `src/handlers/detectPatternsViewsHandler.ts` の `toDateOrTime` と
211
+ * `tools/detect_patterns.ts` の `res.summary` が**別々に同じ判定を持っていて片方だけ
212
+ * 暦日に潰れていた**(#288 Phase 2 のレビュー指摘)ので、判定をここに 1 本化した。
213
+ *
214
+ * 値が空 / parse 失敗 / 不正 tz のときは `null` を返す。**フォールバックは呼び出し側が決める**
215
+ * (`'n/a'` を出す側と、元の ISO をそのまま出す側がある)。
216
+ */
217
+ export function formatDateOrTimeInTz(iso: string | number | undefined | null, tz: string, type: string): string | null {
218
+ if (iso == null || iso === '') return null;
219
+ const ms = typeof iso === 'number' ? iso : Date.parse(iso);
220
+ if (!Number.isFinite(ms)) return null;
221
+ if (!isIntradayType(type)) return formatDateInTz(ms, tz);
222
+ const withTz = toIsoWithTz(ms, resolveTz(tz)); // 'YYYY-MM-DDTHH:mm:ss'
223
+ return withTz ? `${withTz.slice(0, 10)} ${withTz.slice(11, 16)}` : null;
224
+ }
225
+
164
226
  /**
165
227
  * ISO日付文字列を "M/D(曜日)" 形式に変換
166
228
  * 例: "2026-04-09T00:00:00Z" → "4/9(木)"
package/lib/http.ts CHANGED
@@ -43,6 +43,99 @@ export interface FetchJsonOptions {
43
43
  /** リトライ待機の上限(30秒) */
44
44
  const MAX_RETRY_WAIT_MS = 30_000;
45
45
 
46
+ /**
47
+ * HTTP ステータス由来の失敗。**リトライしてよいかを呼び出し側が判定できる**ようにするため、
48
+ * ステータスコードを保持する(`message` は従来どおり `HTTP <status> <statusText>`。
49
+ * `get_candles` 等が本文の `404` を正規表現で拾っているので文言は変えない)。
50
+ */
51
+ export class HttpStatusError extends Error {
52
+ readonly status: number;
53
+
54
+ constructor(status: number, statusText: string) {
55
+ super(`HTTP ${status} ${statusText}`);
56
+ this.name = 'HttpStatusError';
57
+ this.status = status;
58
+ }
59
+ }
60
+
61
+ /**
62
+ * この HTTP ステータスをもう一度叩く価値があるか。
63
+ *
64
+ * 4xx は上流の「その資源は無い / 要求が不正」の表明で、**同じ URL を叩き直しても永久に同じ結果**
65
+ * になる。bitbank `/candlestick` は上場前・未来の期間キーに 404 を返すため
66
+ * (`docs/internal/bitbank-candle-tz.md`)、ここをリトライすると上場前の 1 chunk につき
67
+ * リクエストが 3 倍になり、レート制限を自分で誘発して**他の chunk の成功率を下げる**(#84)。
68
+ *
69
+ * 例外は 2 つだけ:
70
+ * - 408 Request Timeout: 一時的な遅延なので再試行の価値がある
71
+ * - 429 Too Many Requests: `Retry-After` を解釈する専用経路で扱う(ここには到達しない)
72
+ */
73
+ export function isRetriableHttpStatus(status: number): boolean {
74
+ if (status === 408 || status === 429) return true;
75
+ return status < 400 || status >= 500;
76
+ }
77
+
78
+ /** 汎用リトライの待機ベース(ms)。試行回数 i に対して BASE * 2^i を待つ */
79
+ const RETRY_BACKOFF_BASE_MS = 200;
80
+
81
+ /**
82
+ * i 回目(0 始まり)の試行が失敗したあとの待機ミリ秒。
83
+ * bitbank API へのリトライ待機はすべてこの 1 か所に揃える(呼び出し側で式を書き起こさない)。
84
+ */
85
+ export function retryBackoffMs(attemptIndex: number): number {
86
+ return Math.min(RETRY_BACKOFF_BASE_MS * 2 ** attemptIndex, MAX_RETRY_WAIT_MS);
87
+ }
88
+
89
+ export interface RetryAsyncOptions<T> {
90
+ /** 再試行回数(初回 + N 回)。既定は `DEFAULT_RETRIES` */
91
+ retries?: number;
92
+ /**
93
+ * 戻り値を見て「もう一度やる価値があるか」を判定する。
94
+ * 恒久的な失敗(何度叩いても同じ結果になるもの)で `true` を返すと無駄な負荷になるため、
95
+ * **一時的な失敗だけ** `true` を返すこと。
96
+ */
97
+ shouldRetry: (value: T) => boolean;
98
+ }
99
+
100
+ /**
101
+ * `Result` のように**戻り値で失敗を表す**非同期処理をリトライする汎用ヘルパー。
102
+ *
103
+ * `fetchJson` / `fetchJsonWithRateLimit` は HTTP 1 本のリトライを担当するが、
104
+ * 「ツール呼び出し 1 回(=複数 chunk の取得と成否判定)」の単位でやり直したい層
105
+ * (例: `fetchFlowDatePrices` の年 chunk 取得)は戻り値で失敗を受け取るため、そちらでは使えない。
106
+ * 待機スケジュールを各所で書き起こさないよう `retryBackoffMs` を共有する。
107
+ *
108
+ * semantics:
109
+ * - `operation` が throw した場合は一時的な失敗とみなして再試行し、
110
+ * 使い切ったら最後の例外をそのまま再 throw する(`fetchJson` と同じ)
111
+ * - `operation` が値を返し `shouldRetry(value)` が `true` なら再試行し、
112
+ * 使い切ったら**最後の値をそのまま返す**(失敗の分類は呼び出し側の責務)
113
+ *
114
+ * 注意: `Retry-After` の解釈は HTTP レイヤ(`fetchJsonWithRateLimit`)が担当する。
115
+ * 本ヘルパーはその外側でもう一度試すだけで、ヘッダを二重に解釈しない。
116
+ */
117
+ export async function retryAsync<T>(operation: () => Promise<T>, options: RetryAsyncOptions<T>): Promise<T> {
118
+ const retries = options.retries ?? DEFAULT_RETRIES;
119
+ let lastErr: unknown;
120
+ let hasValue = false;
121
+ let lastValue: T | undefined;
122
+ for (let i = 0; i <= retries; i++) {
123
+ try {
124
+ const value = await operation();
125
+ if (!options.shouldRetry(value)) return value;
126
+ hasValue = true;
127
+ lastValue = value;
128
+ lastErr = undefined;
129
+ } catch (e) {
130
+ lastErr = e;
131
+ hasValue = false;
132
+ }
133
+ if (i < retries) await new Promise((r) => setTimeout(r, retryBackoffMs(i)));
134
+ }
135
+ if (hasValue) return lastValue as T;
136
+ throw lastErr;
137
+ }
138
+
46
139
  /**
47
140
  * Retry-After ヘッダから待機ミリ秒を算出する。
48
141
  * 未指定・不正値の場合はフォールバック値を返す。いずれも MAX_RETRY_WAIT_MS でキャップ。
@@ -75,14 +168,17 @@ export async function fetchJson<T = unknown>(
75
168
  }
76
169
  throw new Error('レート制限超過 (HTTP 429)。しばらく待ってから再試行してください');
77
170
  }
78
- if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
171
+ if (!res.ok) throw new HttpStatusError(res.status, res.statusText);
79
172
  const json: unknown = await res.json();
80
173
  if (schema) return schema.parse(json) as T;
81
174
  return json as T;
82
175
  } catch (e) {
83
176
  clearTimeout(t);
84
177
  lastErr = e;
85
- if (i < retries) await new Promise((r) => setTimeout(r, 200 * 2 ** i));
178
+ // 恒久的な HTTP 失敗(404 等)はリトライしない。何度叩いても同じ結果で、
179
+ // 待ち時間とレート制限枠だけを消費する(#84)。
180
+ if (e instanceof HttpStatusError && !isRetriableHttpStatus(e.status)) break;
181
+ if (i < retries) await new Promise((r) => setTimeout(r, retryBackoffMs(i)));
86
182
  }
87
183
  }
88
184
  throw lastErr;
@@ -117,7 +213,7 @@ export async function fetchJsonWithRateLimit<T = unknown>(
117
213
  }
118
214
  throw new Error('レート制限超過 (HTTP 429)。しばらく待ってから再試行してください');
119
215
  }
120
- if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
216
+ if (!res.ok) throw new HttpStatusError(res.status, res.statusText);
121
217
  const rateLimit = extractRateLimit(res.headers);
122
218
  const json: unknown = await res.json();
123
219
  const data = schema ? (schema.parse(json) as T) : (json as T);
@@ -125,7 +221,10 @@ export async function fetchJsonWithRateLimit<T = unknown>(
125
221
  } catch (e) {
126
222
  clearTimeout(t);
127
223
  lastErr = e;
128
- if (i < retries) await new Promise((r) => setTimeout(r, 200 * 2 ** i));
224
+ // 恒久的な HTTP 失敗(404 等)はリトライしない。何度叩いても同じ結果で、
225
+ // 待ち時間とレート制限枠だけを消費する(#84)。
226
+ if (e instanceof HttpStatusError && !isRetriableHttpStatus(e.status)) break;
227
+ if (i < retries) await new Promise((r) => setTimeout(r, retryBackoffMs(i)));
129
228
  }
130
229
  }
131
230
  throw lastErr;
package/lib/pairs.ts CHANGED
@@ -220,6 +220,64 @@ export async function fetchPairsSpec(opts: FetchPairsSpecOptions = {}): Promise<
220
220
  }
221
221
  }
222
222
 
223
+ // ── 価格の丸め ──
224
+
225
+ /**
226
+ * 価格をペアの `price_digits` 桁で丸める。
227
+ *
228
+ * 表示層が価格を無条件に整数化すると低価格ペアが壊れる(XLM 26.686 → 27 で誤差 1.4%)ため、
229
+ * ペアごとの最小値刻み(10^-price_digits)に合わせて丸めるためのヘルパー。
230
+ *
231
+ * - `value` が `undefined` / 非有限なら `undefined`(呼び出し側の欠損経路をそのまま通す)
232
+ * - **`spec` が無いときは丸めずに生値を返す。** `/spot/pairs` の取得失敗や未知ペアで
233
+ * 整数丸めにフォールバックしてはならない(低価格ペアを壊すバグの再導入になる)
234
+ * - `extraDigits` は板の刻みに縛られない値(平均取得単価など)に桁の余裕を持たせるための加算
235
+ * - 半刻みは +∞ 方向に倒す(`Math.round` と同じ)。2 進の乗算誤差で半刻みを取りこぼさない
236
+ *
237
+ * @example
238
+ * roundToPriceDigits(26.686000000000003, xlmSpec) // 26.686 (price_digits=3)
239
+ * roundToPriceDigits(15015015.015, btcSpec) // 15015015 (price_digits=0)
240
+ * roundToPriceDigits(26.686000000000003, undefined) // 26.686000000000003(素通し)
241
+ * roundToPriceDigits(15015015.015, btcSpec, { extraDigits: 2 }) // 15015015.02
242
+ */
243
+ export function roundToPriceDigits(
244
+ value: number | undefined,
245
+ spec: PairSpec | undefined,
246
+ opts: { extraDigits?: number } = {},
247
+ ): number | undefined {
248
+ if (value == null || !Number.isFinite(value)) return undefined;
249
+ if (spec == null) return value;
250
+ const digits = spec.price_digits + (opts.extraDigits ?? 0);
251
+ if (!Number.isFinite(digits) || digits < 0) return value;
252
+ const rounded = roundAtDecimalDigits(value, digits);
253
+ // 巨大値が Infinity に飛んだ場合は丸めを諦めて生値を返す。
254
+ return Number.isFinite(rounded) ? rounded : value;
255
+ }
256
+
257
+ /**
258
+ * 10 進 `digits` 桁で丸める。半刻みは `Math.round` と同じく +∞ 方向。
259
+ *
260
+ * 素朴な `Math.round(value * 10 ** digits) / 10 ** digits` は 2 進の乗算誤差で
261
+ * ちょうど半刻みの値を取りこぼす(`1.005 * 100 === 100.49999999999999` なので
262
+ * `Math.round` が 100 に落ち、1.01 ではなく 1 が返る)。
263
+ * `Number` の 10 進文字列パースを経由して指数だけをずらせば、この乗算を挟まずに
264
+ * 桁をシフトできる(`"1.005e2"` → `100.5`)。
265
+ *
266
+ * 半刻みを +∞ 方向に倒すのは意図的で、円建て金額の `Math.round` と揃えるため
267
+ * (`-1.005` は `-1.01` ではなく `-1`)。
268
+ */
269
+ function roundAtDecimalDigits(value: number, digits: number): number {
270
+ const shifted = Number(`${value}e${digits}`);
271
+ if (Number.isFinite(shifted)) {
272
+ const back = Number(`${Math.round(shifted)}e${-digits}`);
273
+ if (Number.isFinite(back)) return back;
274
+ }
275
+ // 値そのものや丸め結果が指数表記に化けると上の文字列が "1e-7e4" のように
276
+ // 不正になり Number が NaN を返す。その場合だけ素朴な乗算に落とす。
277
+ const factor = 10 ** digits;
278
+ return Math.round(value * factor) / factor;
279
+ }
280
+
223
281
  // ── 注文事前バリデーション ──
224
282
 
225
283
  export interface OrderConstraintsInput {