@interactive-inc/claude-funnel 0.52.0 → 0.55.0

package/README.md

@@ -16,7 +16,7 @@ Slack のメンション、GitHub の Issue、毎朝 9 時の cron。こうし
    返信は同じコネクタを逆向きに通る（エージェント → MCP tool → 外部サービス）。
 ```
 
-コマンドは `funnel`（短縮形 `fnl`）。Claude Code を中心に作っているが、アーキテクチャはエージェント非依存。現在のバージョンは `0.49.0`。
+コマンドは `funnel`（短縮形 `fnl`）。Claude Code を中心に作っているが、アーキテクチャはエージェント非依存。現在のバージョンは `0.53.0`。
 
 ## funnel がやること
 
@@ -349,8 +349,8 @@ funnel.channels.addConnector("inbox", {
 `channels` / `profiles` / `gateway` / `listeners` / `claude` / `localConfig` / `localConfigSync` など全ファセットが同じインスタンスの readonly プロパティとして辿れる。`gateway` はデーモンの起動・停止、`listeners` は動作中デーモンとの HTTP 会話、`claude` はエージェント起動を担う。
 
 ```ts
-await funnel.gateway.start()    // デーモンを別プロセスとして spawn
-funnel.gateway.getStatus()      // { running, pid, port }
+await funnel.gateway.start() // デーモンを別プロセスとして spawn
+funnel.gateway.getStatus() // { running, pid, port }
 
 await funnel.listeners.start("inbox", "my-slack")
 await funnel.listeners.restart("inbox", "my-slack")
@@ -375,6 +375,28 @@ unsubscribe()
 
 永続化と再生は `FunnelEventLog` port の裏にある。デフォルトは `SqliteFunnelEventLog`（デーモン再起動を跨いで durable。reconnect 時の再生を提供する）。`gatewayServer({ eventLog })` に `MemoryFunnelEventLog` を渡せば durable な再生を差し替え・無効化できる。`onEvent` は書き込み専用の観測フックで、再生（読み戻し）は EventLog の責務。
 
+### 間違えにくい API
+
+URL やオプションは型で安全側に倒している。
+
+```ts
+import {
+  channelWsUrl,
+  channelWsProtocols,
+  gatewayLoopbackUrl,
+} from "@interactive-inc/claude-funnel/gateway"
+
+// WS 購読 URL。channel は必須（付け忘れるとコンパイルエラー）。
+const url = channelWsUrl({ base: "ws://localhost:9743/ws", channel: "inbox", subscriberId })
+const ws = new WebSocket(url, channelWsProtocols(token)) // token は subprotocol で渡す
+
+// HTTP の loopback base は手で組まずこれを使う
+const base = gatewayLoopbackUrl(9743) // → http://127.0.0.1:9743
+```
+
+- 非ループバック bind（`gatewayServer({ hostname: "0.0.0.0" })`）は token 無しだと `start()` が throw する。前段で自前認証する場合のみ `allowInsecureHost: true`
+- コネクタの token は `botToken` か `botTokenEnv` の片方だけ（両方同時はコンパイルエラー）、event store は `dbPath` か `eventLog` の片方だけ、launch の `resume` は `profileId` がある時だけ指定できる
+
 ### サブエントリ
 
 個別の層だけを import したい場合は sub-entry を使う。