@kodelyth/line 2026.5.39 → 2026.5.42

package/src/channel.status.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import type { ChannelAccountSnapshot } from "../api.js";
+import { lineStatusAdapter } from "./status.js";
+
+function collectIssues(accounts: ChannelAccountSnapshot[]) {
+  const collect = lineStatusAdapter.collectStatusIssues;
+  if (!collect) {
+    throw new Error("LINE plugin status collector is unavailable");
+  }
+  return collect(accounts);
+}
+
+describe("linePlugin status.collectStatusIssues", () => {
+  it("does not warn when a sanitized snapshot is configured", () => {
+    expect(
+      collectIssues([
+        {
+          accountId: "default",
+          configured: true,
+          tokenSource: "env",
+        },
+      ]),
+    ).toStrictEqual([]);
+  });
+
+  it("reports missing access token when the snapshot is unconfigured and tokenSource is none", () => {
+    expect(
+      collectIssues([
+        {
+          accountId: "default",
+          configured: false,
+          tokenSource: "none",
+        },
+      ]),
+    ).toEqual([
+      {
+        channel: "line",
+        accountId: "default",
+        kind: "config",
+        message: "LINE channel access token not configured",
+      },
+    ]);
+  });
+
+  it("reports missing secret when the snapshot is unconfigured but a token source exists", () => {
+    expect(
+      collectIssues([
+        {
+          accountId: "default",
+          configured: false,
+          tokenSource: "env",
+        },
+      ]),
+    ).toEqual([
+      {
+        channel: "line",
+        accountId: "default",
+        kind: "config",
+        message: "LINE channel secret not configured",
+      },
+    ]);
+  });
+});

package/src/channel.ts

@@ -0,0 +1,155 @@
+import { createChatChannelPlugin } from "klaw/plugin-sdk/channel-core";
+import { createPairingPrefixStripper } from "klaw/plugin-sdk/channel-pairing";
+import { createRestrictSendersChannelSecurity } from "klaw/plugin-sdk/channel-policy";
+import { createEmptyChannelDirectoryAdapter } from "klaw/plugin-sdk/directory-runtime";
+import { createLazyRuntimeModule } from "klaw/plugin-sdk/lazy-runtime";
+import { resolveLineAccount } from "./accounts.js";
+import { lineBindingsAdapter } from "./bindings.js";
+import { type ChannelPlugin, type ResolvedLineAccount } from "./channel-api.js";
+import { lineChannelPluginCommon } from "./channel-shared.js";
+import { lineGatewayAdapter } from "./gateway.js";
+import { resolveLineGroupRequireMention } from "./group-policy.js";
+import { lineMessageAdapter, lineOutboundAdapter } from "./outbound.js";
+import { hasLineDirectives, parseLineDirectives } from "./reply-payload-transform.js";
+import { getLineRuntime } from "./runtime.js";
+import { lineSetupAdapter } from "./setup-core.js";
+import { lineSetupWizard } from "./setup-surface.js";
+import { lineStatusAdapter } from "./status.js";
+
+const loadLineChannelRuntime = createLazyRuntimeModule(() => import("./channel.runtime.js"));
+
+const lineSecurityAdapter = createRestrictSendersChannelSecurity<ResolvedLineAccount>({
+  channelKey: "line",
+  resolveDmPolicy: (account) => account.config.dmPolicy,
+  resolveDmAllowFrom: (account) => account.config.allowFrom,
+  resolveGroupPolicy: (account) => account.config.groupPolicy,
+  surface: "LINE groups",
+  openScope: "any member in groups",
+  groupPolicyPath: "channels.line.groupPolicy",
+  groupAllowFromPath: "channels.line.groupAllowFrom",
+  mentionGated: false,
+  policyPathSuffix: "dmPolicy",
+  approveHint: "klaw pairing approve line <code>",
+  normalizeDmEntry: (raw) => raw.replace(/^line:(?:user:)?/i, ""),
+});
+
+export const linePlugin: ChannelPlugin<ResolvedLineAccount> = createChatChannelPlugin({
+  base: {
+    id: "line",
+    ...lineChannelPluginCommon,
+    setupWizard: lineSetupWizard,
+    groups: {
+      resolveRequireMention: resolveLineGroupRequireMention,
+    },
+    messaging: {
+      targetPrefixes: ["line"],
+      normalizeTarget: (target) => {
+        const trimmed = target.trim();
+        if (!trimmed) {
+          return undefined;
+        }
+        return trimmed.replace(/^line:(group|room|user):/i, "").replace(/^line:/i, "");
+      },
+      resolveInboundConversation: lineBindingsAdapter.resolveInboundConversation,
+      transformReplyPayload: ({ payload }) => {
+        if (!payload.text || !hasLineDirectives(payload.text)) {
+          return payload;
+        }
+        return parseLineDirectives(payload);
+      },
+      targetResolver: {
+        looksLikeId: (id) => {
+          const trimmed = id?.trim();
+          if (!trimmed) {
+            return false;
+          }
+          return /^[UCR][a-f0-9]{32}$/i.test(trimmed) || /^line:/i.test(trimmed);
+        },
+        hint: "<userId|groupId|roomId>",
+      },
+    },
+    directory: createEmptyChannelDirectoryAdapter(),
+    setup: lineSetupAdapter,
+    status: lineStatusAdapter,
+    gateway: lineGatewayAdapter,
+    message: lineMessageAdapter,
+    bindings: lineBindingsAdapter,
+    conversationBindings: {
+      defaultTopLevelPlacement: "current",
+    },
+    agentPrompt: {
+      messageToolHints: () => [
+        "",
+        "### LINE Rich Messages",
+        "LINE supports rich visual messages. Use these directives in your reply when appropriate:",
+        "",
+        "**Quick Replies** (bottom button suggestions):",
+        "  [[quick_replies: Option 1, Option 2, Option 3]]",
+        "",
+        "**Location** (map pin):",
+        "  [[location: Place Name | Address | latitude | longitude]]",
+        "",
+        "**Confirm Dialog** (yes/no prompt):",
+        "  [[confirm: Question text? | Yes Label | No Label]]",
+        "",
+        "**Button Menu** (title + text + buttons):",
+        "  [[buttons: Title | Description | Btn1:action1, Btn2:https://url.com]]",
+        "",
+        "**Media Player Card** (music status):",
+        "  [[media_player: Song Title | Artist Name | Source | https://albumart.url | playing]]",
+        "  - Status: 'playing' or 'paused' (optional)",
+        "",
+        "**Event Card** (calendar events, meetings):",
+        "  [[event: Event Title | Date | Time | Location | Description]]",
+        "  - Time, Location, Description are optional",
+        "",
+        "**Agenda Card** (multiple events/schedule):",
+        "  [[agenda: Schedule Title | Event1:9:00 AM, Event2:12:00 PM, Event3:3:00 PM]]",
+        "",
+        "**Device Control Card** (smart devices, TVs, etc.):",
+        "  [[device: Device Name | Device Type | Status | Control1:data1, Control2:data2]]",
+        "",
+        "**Apple TV Remote** (full D-pad + transport):",
+        "  [[appletv_remote: Apple TV | Playing]]",
+        "",
+        "**Auto-converted**: Markdown tables become Flex cards, code blocks become styled cards.",
+        "",
+        "When to use rich messages:",
+        "- Use [[quick_replies:...]] when offering 2-4 clear options",
+        "- Use [[confirm:...]] for yes/no decisions",
+        "- Use [[buttons:...]] for menus with actions/links",
+        "- Use [[location:...]] when sharing a place",
+        "- Use [[media_player:...]] when showing what's playing",
+        "- Use [[event:...]] for calendar event details",
+        "- Use [[agenda:...]] for a day's schedule or event list",
+        "- Use [[device:...]] for smart device status/controls",
+        "- Tables/code in your response auto-convert to visual cards",
+      ],
+    },
+  },
+  pairing: {
+    text: {
+      idLabel: "lineUserId",
+      message: "Klaw: your access has been approved.",
+      normalizeAllowEntry: createPairingPrefixStripper(/^line:(?:user:)?/i),
+      notify: async ({ cfg, id, message }) => {
+        const account = (getLineRuntime().channel.line?.resolveLineAccount ?? resolveLineAccount)({
+          cfg,
+        });
+        if (!account.channelAccessToken) {
+          throw new Error("LINE channel access token not configured");
+        }
+        const pushMessageLine =
+          getLineRuntime().channel.line?.pushMessageLine ??
+          (await loadLineChannelRuntime()).pushMessageLine;
+        await pushMessageLine(id, message, {
+          cfg,
+          accountId: account.accountId,
+          channelAccessToken: account.channelAccessToken,
+        });
+      },
+    },
+  },
+  security: lineSecurityAdapter,
+  outbound: lineOutboundAdapter,
+});

package/src/config-adapter.ts

@@ -0,0 +1,29 @@
+import { createScopedChannelConfigAdapter } from "klaw/plugin-sdk/channel-config-helpers";
+import {
+  listLineAccountIds,
+  resolveDefaultLineAccountId,
+  resolveLineAccount,
+  type ResolvedLineAccount,
+} from "./channel-api.js";
+
+function normalizeLineAllowFrom(entry: string): string {
+  return entry.replace(/^line:(?:user:)?/i, "");
+}
+
+export const lineConfigAdapter = createScopedChannelConfigAdapter<
+  ResolvedLineAccount,
+  ResolvedLineAccount
+>({
+  sectionKey: "line",
+  listAccountIds: listLineAccountIds,
+  resolveAccount: (cfg, accountId) =>
+    resolveLineAccount({ cfg, accountId: accountId ?? undefined }),
+  defaultAccountId: resolveDefaultLineAccountId,
+  clearBaseFields: ["channelSecret", "tokenFile", "secretFile"],
+  resolveAllowFrom: (account) => account.config.allowFrom,
+  formatAllowFrom: (allowFrom) =>
+    allowFrom
+      .map((entry) => String(entry).trim())
+      .filter(Boolean)
+      .map(normalizeLineAllowFrom),
+});

package/src/config-schema.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { LineConfigSchema } from "./config-schema.js";
+
+describe("LineConfigSchema", () => {
+  it('rejects dmPolicy="open" without wildcard allowFrom', () => {
+    const result = LineConfigSchema.safeParse({
+      channelAccessToken: "token",
+      channelSecret: "secret",
+      dmPolicy: "open",
+    });
+
+    if (result.success) {
+      throw new Error("Expected config validation to fail");
+    }
+    expect(result.error.issues).toHaveLength(1);
+    expect(result.error.issues[0]?.path).toEqual(["allowFrom"]);
+    expect(result.error.issues[0]?.message).toBe(
+      'channels.line.dmPolicy="open" requires channels.line.allowFrom to include "*"',
+    );
+  });
+
+  it('accepts dmPolicy="open" with wildcard allowFrom', () => {
+    const result = LineConfigSchema.safeParse({
+      channelAccessToken: "token",
+      channelSecret: "secret",
+      dmPolicy: "open",
+      allowFrom: ["*"],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects account dmPolicy="open" without wildcard allowFrom', () => {
+    const result = LineConfigSchema.safeParse({
+      accounts: {
+        work: {
+          channelAccessToken: "token",
+          channelSecret: "secret",
+          dmPolicy: "open",
+        },
+      },
+    });
+
+    if (result.success) {
+      throw new Error("Expected account config validation to fail");
+    }
+    expect(result.error.issues).toHaveLength(1);
+    expect(result.error.issues[0]?.path).toEqual(["accounts", "work", "allowFrom"]);
+    expect(result.error.issues[0]?.message).toBe(
+      'channels.line.dmPolicy="open" requires channels.line.allowFrom to include "*"',
+    );
+  });
+});

package/src/config-schema.ts

@@ -0,0 +1,81 @@
+import {
+  buildChannelConfigSchema,
+  requireOpenAllowFrom,
+} from "klaw/plugin-sdk/channel-config-schema";
+import { requireChannelOpenAllowFrom } from "klaw/plugin-sdk/extension-shared";
+import { z } from "zod";
+
+const DmPolicySchema = z.enum(["open", "allowlist", "pairing", "disabled"]);
+const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
+const ThreadBindingsSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    idleHours: z.number().optional(),
+    maxAgeHours: z.number().optional(),
+    spawnSessions: z.boolean().optional(),
+    defaultSpawnContext: z.enum(["isolated", "fork"]).optional(),
+    spawnSubagentSessions: z.boolean().optional(),
+    spawnAcpSessions: z.boolean().optional(),
+  })
+  .strict();
+
+const LineCommonConfigSchemaBase = z.object({
+  enabled: z.boolean().optional(),
+  channelAccessToken: z.string().optional(),
+  channelSecret: z.string().optional(),
+  tokenFile: z.string().optional(),
+  secretFile: z.string().optional(),
+  name: z.string().optional(),
+  allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  dmPolicy: DmPolicySchema.optional().default("pairing"),
+  groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+  responsePrefix: z.string().optional(),
+  mediaMaxMb: z.number().optional(),
+  webhookPath: z.string().optional(),
+  threadBindings: ThreadBindingsSchema.optional(),
+});
+
+const LineGroupConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    requireMention: z.boolean().optional(),
+    systemPrompt: z.string().optional(),
+    skills: z.array(z.string()).optional(),
+  })
+  .strict();
+
+const LineAccountConfigSchema = LineCommonConfigSchemaBase.extend({
+  groups: z.record(z.string(), LineGroupConfigSchema.optional()).optional(),
+})
+  .strict()
+  .superRefine((value, ctx) => {
+    requireChannelOpenAllowFrom({
+      channel: "line",
+      policy: value.dmPolicy,
+      allowFrom: value.allowFrom,
+      ctx,
+      requireOpenAllowFrom,
+    });
+  });
+
+export const LineConfigSchema = LineCommonConfigSchemaBase.extend({
+  accounts: z.record(z.string(), LineAccountConfigSchema.optional()).optional(),
+  defaultAccount: z.string().optional(),
+  groups: z.record(z.string(), LineGroupConfigSchema.optional()).optional(),
+})
+  .strict()
+  .superRefine((value, ctx) => {
+    requireChannelOpenAllowFrom({
+      channel: "line",
+      policy: value.dmPolicy,
+      allowFrom: value.allowFrom,
+      ctx,
+      requireOpenAllowFrom,
+    });
+  });
+
+export const LineChannelConfigSchema = buildChannelConfigSchema(LineConfigSchema);
+
+export type LineConfigSchemaType = z.infer<typeof LineConfigSchema>;

package/src/download.test.ts

@@ -0,0 +1,164 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const getMessageContentMock = vi.hoisted(() => vi.fn());
+const saveMediaStreamMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@line/bot-sdk", () => ({
+  messagingApi: {
+    MessagingApiBlobClient: class {
+      getMessageContent(messageId: string) {
+        return getMessageContentMock(messageId);
+      }
+    },
+  },
+}));
+
+vi.mock("klaw/plugin-sdk/runtime-env", () => ({
+  createSubsystemLogger: () => {
+    const logger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      child: () => logger,
+    };
+    return logger;
+  },
+  logVerbose: () => {},
+}));
+
+vi.mock("klaw/plugin-sdk/media-store", () => ({
+  saveMediaStream: saveMediaStreamMock,
+}));
+
+let downloadLineMedia: typeof import("./download.js").downloadLineMedia;
+
+async function* chunks(parts: Buffer[]): AsyncGenerator<Buffer> {
+  for (const part of parts) {
+    yield part;
+  }
+}
+
+function saveMediaStreamCall(): unknown[] {
+  const call = saveMediaStreamMock.mock.calls.at(0);
+  if (!call) {
+    throw new Error("Expected saveMediaStream call");
+  }
+  return call;
+}
+
+function detectMockContentType(buffer: Buffer, contentType?: string): string | undefined {
+  if (buffer[0] === 0xff && buffer[1] === 0xd8) {
+    return "image/jpeg";
+  }
+  if (buffer.toString("ascii", 4, 8) === "ftyp") {
+    return buffer.toString("ascii", 8, 12) === "M4A " ? "audio/x-m4a" : "video/mp4";
+  }
+  return contentType;
+}
+
+describe("downloadLineMedia", () => {
+  beforeAll(async () => {
+    ({ downloadLineMedia } = await import("./download.js"));
+  });
+
+  afterAll(() => {
+    vi.doUnmock("@line/bot-sdk");
+    vi.doUnmock("klaw/plugin-sdk/runtime-env");
+    vi.doUnmock("klaw/plugin-sdk/media-store");
+    vi.resetModules();
+  });
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    getMessageContentMock.mockReset();
+    saveMediaStreamMock.mockReset();
+    saveMediaStreamMock.mockImplementation(
+      async (stream: AsyncIterable<Buffer>, contentType?: string, subdir?: string) => {
+        const chunks: Buffer[] = [];
+        for await (const chunk of stream) {
+          chunks.push(Buffer.from(chunk));
+        }
+        const buffer = Buffer.concat(chunks);
+        return {
+          path: `/home/user/.klaw/media/${subdir ?? "unknown"}/saved-media`,
+          contentType: detectMockContentType(buffer, contentType),
+          size: buffer.length,
+        };
+      },
+    );
+  });
+
+  it("persists inbound media with the shared media store", async () => {
+    const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0x00]);
+    getMessageContentMock.mockResolvedValueOnce(chunks([jpeg]));
+
+    const result = await downloadLineMedia("mid-jpeg", "token");
+
+    expect(saveMediaStreamMock).toHaveBeenCalledTimes(1);
+    const call = saveMediaStreamCall();
+    expect(call[1]).toBeUndefined();
+    expect(call[2]).toBe("inbound");
+    expect(call[3]).toBe(10 * 1024 * 1024);
+    expect(result).toEqual({
+      path: "/home/user/.klaw/media/inbound/saved-media",
+      contentType: "image/jpeg",
+      size: jpeg.length,
+    });
+  });
+
+  it("does not pass the external messageId to saveMediaStream", async () => {
+    const messageId = "a/../../../../etc/passwd";
+    const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0x00]);
+    getMessageContentMock.mockResolvedValueOnce(chunks([jpeg]));
+
+    const result = await downloadLineMedia(messageId, "token");
+
+    expect(result.size).toBe(jpeg.length);
+    expect(result.contentType).toBe("image/jpeg");
+    for (const arg of saveMediaStreamCall()) {
+      if (typeof arg === "string") {
+        expect(arg).not.toContain(messageId);
+      }
+    }
+  });
+
+  it("delegates oversized media rejection to saveMediaStream", async () => {
+    getMessageContentMock.mockResolvedValueOnce(chunks([Buffer.alloc(4), Buffer.alloc(4)]));
+    saveMediaStreamMock.mockRejectedValueOnce(new Error("Media exceeds 0MB limit"));
+
+    await expect(downloadLineMedia("mid", "token", 7)).rejects.toThrow(/Media exceeds/i);
+    expect(saveMediaStreamMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("uses media store content type for M4A media", async () => {
+    const m4aHeader = Buffer.from([
+      0x00, 0x00, 0x00, 0x1c, 0x66, 0x74, 0x79, 0x70, 0x4d, 0x34, 0x41, 0x20,
+    ]);
+    getMessageContentMock.mockResolvedValueOnce(chunks([m4aHeader]));
+
+    const result = await downloadLineMedia("mid-audio", "token");
+
+    expect(result.contentType).toBe("audio/x-m4a");
+    expect(saveMediaStreamCall()[2]).toBe("inbound");
+  });
+
+  it("uses media store content type for MP4 video", async () => {
+    const mp4 = Buffer.from([
+      0x00, 0x00, 0x00, 0x1c, 0x66, 0x74, 0x79, 0x70, 0x69, 0x73, 0x6f, 0x6d,
+    ]);
+    getMessageContentMock.mockResolvedValueOnce(chunks([mp4]));
+
+    const result = await downloadLineMedia("mid-mp4", "token");
+
+    expect(result.contentType).toBe("video/mp4");
+  });
+
+  it("propagates media store failures", async () => {
+    const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0x00]);
+    getMessageContentMock.mockResolvedValueOnce(chunks([jpeg]));
+    saveMediaStreamMock.mockRejectedValueOnce(new Error("Media exceeds 0MB limit"));
+
+    await expect(downloadLineMedia("mid-bad", "token")).rejects.toThrow(/Media exceeds/i);
+  });
+});

package/src/download.ts

@@ -0,0 +1,34 @@
+import { messagingApi } from "@line/bot-sdk";
+import { saveMediaStream } from "klaw/plugin-sdk/media-store";
+import { logVerbose } from "klaw/plugin-sdk/runtime-env";
+
+interface DownloadResult {
+  path: string;
+  contentType?: string;
+  size: number;
+}
+
+export async function downloadLineMedia(
+  messageId: string,
+  channelAccessToken: string,
+  maxBytes = 10 * 1024 * 1024,
+): Promise<DownloadResult> {
+  const client = new messagingApi.MessagingApiBlobClient({
+    channelAccessToken,
+  });
+
+  const response = await client.getMessageContent(messageId);
+  const saved = await saveMediaStream(
+    response as AsyncIterable<Buffer>,
+    undefined,
+    "inbound",
+    maxBytes,
+  );
+  logVerbose(`line: persisted media ${messageId} to ${saved.path} (${saved.size} bytes)`);
+
+  return {
+    path: saved.path,
+    contentType: saved.contentType,
+    size: saved.size,
+  };
+}