@mulmobridge/line 0.1.0 → 1.0.0

package/README.md

@@ -14,7 +14,11 @@ LINE bridge for [MulmoClaude](https://github.com/receptron/mulmoclaude). Uses we
 
 ### 2. Set up ngrok (for development)
 
+[ngrok](https://ngrok.com) is a tunneling tool that exposes a local port to the internet so LINE's webhooks can reach your machine.
+
 ```bash
+brew install ngrok
+ngrok config add-authtoken <your-token>  # from ngrok dashboard
 ngrok http 3002
 # Copy the https://xxxx.ngrok-free.app URL
 ```
@@ -22,9 +26,9 @@ ngrok http 3002
 ### 3. Configure the webhook
 
 In the LINE Developers Console → Messaging API tab:
-- **Webhook URL**: `https://xxxx.ngrok-free.app/webhook`
+- **Webhook URL**: `https://xxxx.ngrok-free.app/webhook` — the trailing `/webhook` is **required** (without it you get 404)
 - **Use webhook**: enabled
-- **Auto-reply messages**: disabled (so LINE's default replies don't interfere)
+- **Auto-reply messages**: disabled (LINE Official Account settings → Auto-reply messages → OFF, otherwise you get double replies)
 
 ### 4. Run the bridge
 
@@ -55,11 +59,80 @@ Scan the QR code in the LINE Developers Console → Messaging API tab. Send a me
 | `LINE_BRIDGE_PORT` | No | Webhook port (default: 3002) |
 | `MULMOCLAUDE_API_URL` | No | Default `http://localhost:3001` |
 | `MULMOCLAUDE_AUTH_TOKEN` | No | Bearer token |
+| `LINE_BRIDGE_DEFAULT_ROLE` | No | Role id to seed new bridge sessions with (e.g. `coder`, `general`). Applied ONLY when a line session first appears — once the user switches role via `/role <id>` the session's own role wins. Unknown role ids silently fall back to the server's default with a warn log. |
+| `BRIDGE_DEFAULT_ROLE` | No | Same as above but shared across every bridge. Transport-specific `LINE_BRIDGE_DEFAULT_ROLE` wins when both are set. |
+
+### Auth token persistence across server restarts
+
+The MulmoClaude server regenerates a fresh bearer token on every startup and writes it to `~/mulmoclaude/.session-token`. The bridge reads that file once at launch and keeps the token in memory — so if the server restarts while the bridge is running, the bridge keeps using the **old** token and every API call returns **401**, silently.
+
+**Fix**: set `MULMOCLAUDE_AUTH_TOKEN` to the same long random value on **both** the server and the bridge. The server uses it verbatim instead of regenerating, so the token survives restarts and the bridge stays authenticated.
+
+```bash
+# Server (one-time setup — same value across restarts)
+MULMOCLAUDE_AUTH_TOKEN=long-random-string yarn dev
+
+# Bridge (separate process / machine — same value)
+MULMOCLAUDE_AUTH_TOKEN=long-random-string \
+  <bridge-specific-envs> \
+  npx <this-package>@latest
+```
+
+Recommended: at least 32 characters of random data (the server logs a warning at startup for shorter values).
 
 ## Notes
 
 - LINE reply tokens expire in **1 minute**. Since Claude responses can take longer, the bridge uses **push messages** instead of reply messages. This requires your bot to be a verified/certified account for push to work with all users, OR the user must have added the bot as a friend first.
 - LINE limits messages to 5 per push call and ~5000 chars per message. Long replies are automatically chunked.
+- **Inbound media** — text and image messages are forwarded to the agent. Image bytes are downloaded via the LINE Data API (`/v2/bot/message/<id>/content`) using the same channel access token; the actual format (JPEG / PNG / HEIC depending on sender) is preserved via the response Content-Type. The photo-EXIF auto-capture flow ([#1222](https://github.com/receptron/mulmoclaude/issues/1222)) writes a sidecar at `data/locations/...` when GPS data is present. Video / audio / file / sticker messages are not forwarded yet.
+
+## Detailed Setup Guide
+
+For step-by-step instructions with troubleshooting:
+
+- [English](https://github.com/receptron/mulmoclaude/blob/main/docs/message_apps/line/README.md)
+- [Japanese](https://github.com/receptron/mulmoclaude/blob/main/docs/message_apps/line/README.ja.md)
+
+## Ecosystem
+
+Part of the [`@mulmobridge/*`](https://www.npmjs.com/~mulmobridge) package family.
+
+**Shared libraries:**
+
+- [`@mulmobridge/client`](https://www.npmjs.com/package/@mulmobridge/client) — socket.io client library used by every bridge below
+- [`@mulmobridge/protocol`](https://www.npmjs.com/package/@mulmobridge/protocol) — wire types and constants
+- [`@mulmobridge/chat-service`](https://www.npmjs.com/package/@mulmobridge/chat-service) — server-side relay + session store
+- [`@mulmobridge/relay`](https://www.npmjs.com/package/@mulmobridge/relay) — Cloudflare Workers webhook proxy
+- [`@mulmobridge/mock-server`](https://www.npmjs.com/package/@mulmobridge/mock-server) — mock server for local bridge development
+
+**Bridges** (one npm package per platform):
+
+- [`@mulmobridge/bluesky`](https://www.npmjs.com/package/@mulmobridge/bluesky) — Bluesky DMs over atproto
+- [`@mulmobridge/chatwork`](https://www.npmjs.com/package/@mulmobridge/chatwork) — Chatwork (Japanese business chat)
+- [`@mulmobridge/cli`](https://www.npmjs.com/package/@mulmobridge/cli) — interactive terminal bridge
+- [`@mulmobridge/discord`](https://www.npmjs.com/package/@mulmobridge/discord) — Discord bot via Gateway
+- [`@mulmobridge/email`](https://www.npmjs.com/package/@mulmobridge/email) — IMAP poll + SMTP reply, threading preserved
+- [`@mulmobridge/google-chat`](https://www.npmjs.com/package/@mulmobridge/google-chat) — Google Chat via MulmoBridge relay
+- [`@mulmobridge/irc`](https://www.npmjs.com/package/@mulmobridge/irc) — IRC (Libera, Freenode, custom)
+- [`@mulmobridge/line`](https://www.npmjs.com/package/@mulmobridge/line) — LINE Messaging API via MulmoBridge relay  ← **this package**
+- [`@mulmobridge/line-works`](https://www.npmjs.com/package/@mulmobridge/line-works) — LINE Works (enterprise LINE)
+- [`@mulmobridge/mastodon`](https://www.npmjs.com/package/@mulmobridge/mastodon) — Mastodon DMs + mentions
+- [`@mulmobridge/matrix`](https://www.npmjs.com/package/@mulmobridge/matrix) — Matrix / Element
+- [`@mulmobridge/mattermost`](https://www.npmjs.com/package/@mulmobridge/mattermost) — Mattermost
+- [`@mulmobridge/messenger`](https://www.npmjs.com/package/@mulmobridge/messenger) — Facebook Messenger via MulmoBridge relay
+- [`@mulmobridge/nostr`](https://www.npmjs.com/package/@mulmobridge/nostr) — Nostr NIP-04 encrypted DMs
+- [`@mulmobridge/rocketchat`](https://www.npmjs.com/package/@mulmobridge/rocketchat) — Rocket.Chat
+- [`@mulmobridge/signal`](https://www.npmjs.com/package/@mulmobridge/signal) — Signal via signal-cli-rest-api
+- [`@mulmobridge/slack`](https://www.npmjs.com/package/@mulmobridge/slack) — Slack Socket Mode
+- [`@mulmobridge/teams`](https://www.npmjs.com/package/@mulmobridge/teams) — Microsoft Teams via Bot Framework
+- [`@mulmobridge/telegram`](https://www.npmjs.com/package/@mulmobridge/telegram) — Telegram bot
+- [`@mulmobridge/twilio-sms`](https://www.npmjs.com/package/@mulmobridge/twilio-sms) — SMS via Twilio Programmable Messaging
+- [`@mulmobridge/viber`](https://www.npmjs.com/package/@mulmobridge/viber) — Viber Public Account bots
+- [`@mulmobridge/webhook`](https://www.npmjs.com/package/@mulmobridge/webhook) — generic HTTP webhook bridge
+- [`@mulmobridge/whatsapp`](https://www.npmjs.com/package/@mulmobridge/whatsapp) — WhatsApp Cloud API via MulmoBridge relay
+- [`@mulmobridge/xmpp`](https://www.npmjs.com/package/@mulmobridge/xmpp) — XMPP / Jabber
+- [`@mulmobridge/zulip`](https://www.npmjs.com/package/@mulmobridge/zulip) — Zulip
+
 
 ## License
 

package/dist/index.js

@@ -13,38 +13,72 @@
 //   MULMOCLAUDE_API_URL       — default http://localhost:3001
 //   MULMOCLAUDE_AUTH_TOKEN    — bearer token
 import "dotenv/config";
-import crypto from "crypto";
-import express from "express";
-import { createBridgeClient } from "@mulmobridge/client";
+import { createBridgeClient, chunkText, formatAckReply } from "@mulmobridge/client";
+import { createWebhookApp, createWebhookRateLimit, verifyHmacSignature } from "@mulmobridge/webhook-runtime";
+import { extractIncomingLineMessage, parseLineWebhookBody } from "./parse.js";
 const TRANSPORT_ID = "line";
 const PORT = Number(process.env.LINE_BRIDGE_PORT) || 3002;
-const channelSecret = process.env.LINE_CHANNEL_SECRET;
-const channelAccessToken = process.env.LINE_CHANNEL_ACCESS_TOKEN;
-if (!channelSecret || !channelAccessToken) {
-    console.error("LINE_CHANNEL_SECRET and LINE_CHANNEL_ACCESS_TOKEN are required.\n" +
-        "See README for setup instructions.");
-    process.exit(1);
+function readRequiredEnv() {
+    const channelSecret = process.env.LINE_CHANNEL_SECRET;
+    const channelAccessToken = process.env.LINE_CHANNEL_ACCESS_TOKEN;
+    if (!channelSecret || !channelAccessToken) {
+        console.error("LINE_CHANNEL_SECRET and LINE_CHANNEL_ACCESS_TOKEN are required.\nSee README for setup instructions.");
+        process.exit(1);
+    }
+    return { channelSecret, channelAccessToken };
 }
+const { channelSecret, channelAccessToken } = readRequiredEnv();
 const client = createBridgeClient({ transportId: TRANSPORT_ID });
-client.onPush((ev) => {
-    pushMessage(ev.chatId, ev.message).catch((err) => console.error(`[line] push send failed: ${err}`));
+client.onPush((pushEvent) => {
+    pushMessage(pushEvent.chatId, pushEvent.message).catch((err) => console.error(`[line] push send failed: ${err}`));
 });
 // ── LINE API helpers ────────────────────────────────────────────
+/** Download an image attached to an inbound LINE message. Returns
+ *  the bytes + Content-Type so the caller can build an Attachment
+ *  envelope for the chat-service socket. Returns null when the
+ *  fetch fails (network error, 4xx, …) — caller logs and skips. */
+async function downloadLineImage(messageId) {
+    try {
+        const res = await fetch(`https://api-data.line.me/v2/bot/message/${encodeURIComponent(messageId)}/content`, {
+            headers: { Authorization: `Bearer ${channelAccessToken}` },
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!res.ok) {
+            console.error(`[line] downloadLineImage failed: ${res.status}`);
+            return null;
+        }
+        // LINE returns image/jpeg by default but the Data API also
+        // serves the original sender format (PNG, GIF, …). Trust the
+        // Content-Type header so the photo-EXIF hook (#1222 PR-A) can
+        // tell HEIC apart from JPEG and surface the right sidecar.
+        const mimeType = res.headers.get("content-type")?.split(";")[0].trim() || "image/jpeg";
+        const arrayBuffer = await res.arrayBuffer();
+        return { bytes: Buffer.from(arrayBuffer), mimeType };
+    }
+    catch (err) {
+        console.error(`[line] downloadLineImage network error: ${err}`);
+        return null;
+    }
+}
 async function pushMessage(userId, text) {
-    const messages = chunkText(text).map((t) => ({ type: "text", text: t }));
+    const messages = chunkText(text, 5000).map((messageText) => ({
+        type: "text",
+        text: messageText,
+    }));
     // LINE allows max 5 messages per push
     for (let i = 0; i < messages.length; i += 5) {
         try {
+            const requestBody = {
+                to: userId,
+                messages: messages.slice(i, i + 5),
+            };
             const res = await fetch("https://api.line.me/v2/bot/message/push", {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
                     Authorization: `Bearer ${channelAccessToken}`,
                 },
-                body: JSON.stringify({
-                    to: userId,
-                    messages: messages.slice(i, i + 5),
-                }),
+                body: JSON.stringify(requestBody),
                 signal: AbortSignal.timeout(30_000),
             });
             if (!res.ok) {
@@ -57,62 +91,52 @@ async function pushMessage(userId, text) {
         }
     }
 }
-function chunkText(text, max = 5000) {
-    if (text.length === 0)
-        return ["(empty reply)"];
-    const chunks = [];
-    for (let i = 0; i < text.length; i += max) {
-        chunks.push(text.slice(i, i + max));
-    }
-    return chunks;
-}
-// ── Signature verification ──────────────────────────────────────
-function verifySignature(body, signature) {
-    const expected = crypto
-        .createHmac("SHA256", channelSecret)
-        .update(body)
-        .digest("base64");
-    if (expected.length !== signature.length)
-        return false;
-    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
-}
 // ── Webhook server ──────────────────────────────────────────────
-const app = express();
-app.disable("x-powered-by");
-app.use(express.text({ type: "application/json" }));
-app.post("/webhook", async (req, res) => {
+const app = createWebhookApp();
+const webhookRateLimit = createWebhookRateLimit();
+app.post("/webhook", webhookRateLimit, async (req, res) => {
     const signature = req.headers["x-line-signature"];
     const bodyStr = req.body;
-    if (!signature || !verifySignature(bodyStr, signature)) {
+    if (!signature || !verifyHmacSignature(bodyStr, signature, channelSecret)) {
         res.status(401).send("Invalid signature");
         return;
     }
     res.status(200).send("OK");
-    let body;
-    try {
-        body = JSON.parse(bodyStr);
-    }
-    catch {
+    const body = parseLineWebhookBody(bodyStr);
+    if (!body) {
         console.error("[line] malformed JSON in webhook body");
         return;
     }
     for (const event of body.events) {
-        if (event.type !== "message" || event.message?.type !== "text")
-            continue;
-        const userId = event.source?.userId;
-        const text = event.message?.text ?? "";
-        if (!userId || !text.trim())
+        const incoming = extractIncomingLineMessage(event);
+        if (!incoming)
             continue;
-        console.log(`[line] message user=${userId} len=${text.length}`);
         try {
-            const ack = await client.send(userId, text);
-            if (ack.ok) {
-                await pushMessage(userId, ack.reply ?? "");
+            if (incoming.kind === "text") {
+                console.log(`[line] message user=${incoming.userId} len=${incoming.text.length}`);
+                const ack = await client.send(incoming.userId, incoming.text);
+                await pushMessage(incoming.userId, formatAckReply(ack));
+                continue;
             }
-            else {
-                const status = ack.status ? ` (${ack.status})` : "";
-                await pushMessage(userId, `Error${status}: ${ack.error ?? "unknown"}`);
+            // kind === "image"
+            console.log(`[line] image user=${incoming.userId} messageId=${incoming.imageMessageId}`);
+            const image = await downloadLineImage(incoming.imageMessageId);
+            if (!image) {
+                await pushMessage(incoming.userId, "Sorry, I couldn't fetch that image.");
+                continue;
             }
+            // chat-service's `parseMessagePayload` rejects empty `text`
+            // (`text is required`) so attachment-only messages need a
+            // placeholder body. Mirror the Telegram convention (see
+            // `packages/bridges/telegram/src/router.ts`) — an instructive
+            // prompt rather than a caption, so the agent treats the
+            // attachment as the subject and produces a useful response.
+            // The post-save EXIF hook (#1222 PR-A) writes a sidecar if
+            // GPS data is present. (Codex review on PR #1255 / #1263.)
+            const attachments = [{ mimeType: image.mimeType, data: image.bytes.toString("base64") }];
+            const placeholderText = "Describe / analyze this file.";
+            const ack = await client.send(incoming.userId, placeholderText, attachments);
+            await pushMessage(incoming.userId, formatAckReply(ack));
         }
         catch (err) {
             console.error(`[line] message handling failed: ${err}`);

package/dist/parse.d.ts

@@ -0,0 +1,45 @@
+export interface LineMessage {
+    type: string;
+    text?: string;
+    /** LINE content id — present on media types (image / video / audio
+     *  / file). The actual bytes live behind a separate Data API call
+     *  (`/v2/bot/message/<id>/content`); the webhook only carries the
+     *  reference. */
+    id?: string;
+}
+export interface LineEvent {
+    type: string;
+    replyToken?: string;
+    source?: {
+        userId?: string;
+        type?: string;
+    };
+    message?: LineMessage;
+}
+export interface LineWebhookBody {
+    events: LineEvent[];
+}
+/** Discriminated union — the webhook may surface text or media.
+ *  Callers branch on `kind` and either send text straight to chat
+ *  or download the media bytes via the LINE Data API.
+ *
+ *  PR-C of #1222: image is the only media kind we forward today.
+ *  Video / audio / file extend this union if/when they become
+ *  worth fanning out to the agent. */
+export type IncomingLineMessage = {
+    kind: "text";
+    userId: string;
+    text: string;
+} | {
+    kind: "image";
+    userId: string;
+    imageMessageId: string;
+};
+/**
+ * Reduce a LINE webhook event to the actionable shape. Returns null
+ * for non-actionable events (non-message types, missing fields,
+ * unsupported media). Pure — no side effects, no allowlist check.
+ */
+export declare function extractIncomingLineMessage(event: LineEvent): IncomingLineMessage | null;
+/** Best-effort JSON parse for the webhook body — null on malformed input. */
+export declare function parseLineWebhookBody(raw: string): LineWebhookBody | null;

package/dist/parse.js

@@ -0,0 +1,39 @@
+// Pure parsing helpers for the LINE bridge webhook.
+/**
+ * Reduce a LINE webhook event to the actionable shape. Returns null
+ * for non-actionable events (non-message types, missing fields,
+ * unsupported media). Pure — no side effects, no allowlist check.
+ */
+export function extractIncomingLineMessage(event) {
+    if (event.type !== "message")
+        return null;
+    const userId = event.source?.userId;
+    if (!userId)
+        return null;
+    const { message } = event;
+    if (!message)
+        return null;
+    if (message.type === "text") {
+        const text = message.text ?? "";
+        if (!text.trim())
+            return null;
+        return { kind: "text", userId, text };
+    }
+    if (message.type === "image" && typeof message.id === "string" && message.id.length > 0) {
+        return { kind: "image", userId, imageMessageId: message.id };
+    }
+    return null;
+}
+/** Best-effort JSON parse for the webhook body — null on malformed input. */
+export function parseLineWebhookBody(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.events)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/line",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "LINE bridge for MulmoBridge — connect a LINE bot to MulmoClaude",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,19 +16,23 @@
     "build": "tsc",
     "prepack": "yarn build",
     "typecheck": "tsc --noEmit",
-    "test": "echo no tests yet"
+    "test": "tsx --test test/test_*.ts",
+    "lint": "eslint src test"
   },
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/client": "^0.1.0",
-    "@mulmobridge/protocol": "^0.1.0",
+    "@mulmobridge/client": "^1.0.0",
+    "@mulmobridge/protocol": "^1.0.0",
+    "@mulmobridge/webhook-runtime": "^1.0.1",
     "dotenv": "^17.0.0",
-    "express": "^5.1.0"
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.6.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3"
   }
 }