@spacebar_ai/moldclaw-core 2026.3.14 → 2026.3.16

package/extensions/kakao-talkchannel/src/kakao/limits.ts

@@ -0,0 +1,129 @@
+import type { KakaoButton, KakaoQuickReply } from "../types.js";
+
+export const KAKAO_LIMITS = {
+  SIMPLE_TEXT_MAX: 1000,
+  SIMPLE_TEXT_VISIBLE: 400,
+
+  CARD_TITLE: 50,
+  CARD_DESCRIPTION: 230,
+
+  BUTTON_LABEL: 14,
+  QUICK_REPLY_LABEL: 14,
+  QUICK_REPLIES_MAX: 10,
+
+  OUTPUTS_MAX: 3,
+  CAROUSEL_MIN: 2,
+  CAROUSEL_MAX: 10,
+  LIST_ITEMS_MIN: 2,
+  LIST_ITEMS_MAX: 5,
+} as const;
+
+export type ValidationResult = { valid: true } | { valid: false; error: string };
+
+export function validateSimpleText(text: string): ValidationResult {
+  if (text.length > KAKAO_LIMITS.SIMPLE_TEXT_MAX) {
+    return {
+      valid: false,
+      error: `Text exceeds ${KAKAO_LIMITS.SIMPLE_TEXT_MAX} characters (got ${text.length})`,
+    };
+  }
+  return { valid: true };
+}
+
+export function validateCardTitle(title: string): ValidationResult {
+  if (title.length > KAKAO_LIMITS.CARD_TITLE) {
+    return {
+      valid: false,
+      error: `Card title exceeds ${KAKAO_LIMITS.CARD_TITLE} characters (got ${title.length})`,
+    };
+  }
+  return { valid: true };
+}
+
+export function validateCardDescription(description: string): ValidationResult {
+  if (description.length > KAKAO_LIMITS.CARD_DESCRIPTION) {
+    return {
+      valid: false,
+      error: `Card description exceeds ${KAKAO_LIMITS.CARD_DESCRIPTION} characters (got ${description.length})`,
+    };
+  }
+  return { valid: true };
+}
+
+export function validateButton(button: KakaoButton): ValidationResult {
+  if (button.label.length > KAKAO_LIMITS.BUTTON_LABEL) {
+    return {
+      valid: false,
+      error: `Button label exceeds ${KAKAO_LIMITS.BUTTON_LABEL} characters (got ${button.label.length})`,
+    };
+  }
+  return { valid: true };
+}
+
+export function validateQuickReply(reply: KakaoQuickReply): ValidationResult {
+  if (reply.label.length > KAKAO_LIMITS.QUICK_REPLY_LABEL) {
+    return {
+      valid: false,
+      error: `Quick reply label exceeds ${KAKAO_LIMITS.QUICK_REPLY_LABEL} characters (got ${reply.label.length})`,
+    };
+  }
+  return { valid: true };
+}
+
+export function validateQuickReplies(replies: KakaoQuickReply[]): ValidationResult {
+  if (replies.length > KAKAO_LIMITS.QUICK_REPLIES_MAX) {
+    return {
+      valid: false,
+      error: `Quick replies exceed max of ${KAKAO_LIMITS.QUICK_REPLIES_MAX} (got ${replies.length})`,
+    };
+  }
+  for (let i = 0; i < replies.length; i++) {
+    const result = validateQuickReply(replies[i]);
+    if (!result.valid) {
+      return { valid: false, error: `Quick reply ${i}: ${result.error}` };
+    }
+  }
+  return { valid: true };
+}
+
+export function validateOutputCount(count: number): ValidationResult {
+  if (count > KAKAO_LIMITS.OUTPUTS_MAX) {
+    return {
+      valid: false,
+      error: `Outputs exceed max of ${KAKAO_LIMITS.OUTPUTS_MAX} (got ${count})`,
+    };
+  }
+  return { valid: true };
+}
+
+export function validateCarouselItemCount(count: number): ValidationResult {
+  if (count < KAKAO_LIMITS.CAROUSEL_MIN) {
+    return {
+      valid: false,
+      error: `Carousel requires at least ${KAKAO_LIMITS.CAROUSEL_MIN} items (got ${count})`,
+    };
+  }
+  if (count > KAKAO_LIMITS.CAROUSEL_MAX) {
+    return {
+      valid: false,
+      error: `Carousel exceeds max of ${KAKAO_LIMITS.CAROUSEL_MAX} items (got ${count})`,
+    };
+  }
+  return { valid: true };
+}
+
+export function validateListItemCount(count: number): ValidationResult {
+  if (count < KAKAO_LIMITS.LIST_ITEMS_MIN) {
+    return {
+      valid: false,
+      error: `List requires at least ${KAKAO_LIMITS.LIST_ITEMS_MIN} items (got ${count})`,
+    };
+  }
+  if (count > KAKAO_LIMITS.LIST_ITEMS_MAX) {
+    return {
+      valid: false,
+      error: `List exceeds max of ${KAKAO_LIMITS.LIST_ITEMS_MAX} items (got ${count})`,
+    };
+  }
+  return { valid: true };
+}

package/extensions/kakao-talkchannel/src/kakao/payload.ts

@@ -0,0 +1,138 @@
+/**
+ * Kakao SkillPayload Parser
+ * 
+ * Parses and validates Kakao SkillPayload, extracting user and message data.
+ * Reference: docs/relay-server-api-spec.md
+ */
+
+import type {
+  KakaoSkillPayload,
+  ParsedKakaoUser,
+} from '../types.js';
+
+export const MAX_UTTERANCE_LENGTH = 5000;
+
+function requireField(obj: Record<string, unknown>, field: string, context: string): void {
+  if (!obj[field]) {
+    throw new Error(`${context} missing required field: ${field}`);
+  }
+}
+
+/**
+ * Parses and validates a Kakao SkillPayload
+ * 
+ * @param body - Unknown input to parse as KakaoSkillPayload
+ * @returns Validated KakaoSkillPayload
+ * @throws Error if payload is invalid or missing required fields
+ */
+export function parseSkillPayload(body: unknown): KakaoSkillPayload {
+  if (body === null || body === undefined || typeof body !== 'object') {
+    throw new Error('SkillPayload must be an object');
+  }
+
+  const payload = body as Record<string, unknown>;
+
+  requireField(payload, 'intent', 'SkillPayload');
+  requireField(payload, 'userRequest', 'SkillPayload');
+  requireField(payload, 'bot', 'SkillPayload');
+  requireField(payload, 'action', 'SkillPayload');
+
+  const userRequest = payload.userRequest as Record<string, unknown>;
+  requireField(userRequest, 'utterance', 'userRequest');
+
+  if (typeof userRequest.utterance !== 'string' || userRequest.utterance.trim() === '') {
+    throw new Error('userRequest.utterance must be a non-empty string');
+  }
+
+  if (userRequest.utterance.length > MAX_UTTERANCE_LENGTH) {
+    throw new Error(`userRequest.utterance exceeds maximum length of ${MAX_UTTERANCE_LENGTH} characters`);
+  }
+
+  requireField(userRequest, 'user', 'userRequest');
+
+  const user = userRequest.user as Record<string, unknown>;
+  requireField(user, 'id', 'userRequest.user');
+
+  return payload as unknown as KakaoSkillPayload;
+}
+
+/**
+ * Extracts user ID from KakaoSkillPayload
+ * 
+ * @param payload - Validated KakaoSkillPayload
+ * @returns User ID (botUserKey)
+ * @throws Error if user.id is missing
+ */
+export function extractUserId(payload: KakaoSkillPayload): string {
+  const userId = payload.userRequest.user.id;
+
+  if (!userId) {
+    throw new Error('Cannot extract userId: user.id is missing');
+  }
+
+  return userId;
+}
+
+/**
+ * Extracts utterance (user message) from KakaoSkillPayload
+ * 
+ * @param payload - Validated KakaoSkillPayload
+ * @returns User utterance text
+ * @throws Error if utterance is missing or empty
+ */
+export function extractUtterance(payload: KakaoSkillPayload): string {
+  const utterance = payload.userRequest.utterance;
+
+  if (!utterance || utterance.trim() === '') {
+    throw new Error('Cannot extract utterance: utterance is missing or empty');
+  }
+
+  return utterance;
+}
+
+/**
+ * Parses Kakao user information from payload
+ * 
+ * Prefers plusfriendUserKey if available, falls back to botUserKey.
+ * 
+ * @param payload - Validated KakaoSkillPayload
+ * @returns ParsedKakaoUser with user identifiers and friend status
+ * @throws Error if user.id is missing
+ */
+export function parseKakaoUser(payload: KakaoSkillPayload): ParsedKakaoUser {
+  const user = payload.userRequest.user;
+
+  if (!user.id) {
+    throw new Error('Cannot parse user: user.id is missing');
+  }
+
+  const plusfriendUserKey = user.properties?.plusfriendUserKey;
+  const isFriend = user.properties?.isFriend ?? false;
+
+  return {
+    botUserKey: user.id,
+    plusfriendUserKey,
+    isFriend,
+  };
+}
+
+/**
+ * Gets callback URL from payload if present
+ * 
+ * @param payload - Validated KakaoSkillPayload
+ * @returns Callback URL or null if not present
+ */
+export function getCallbackUrl(payload: KakaoSkillPayload): string | null {
+  const callbackUrl = payload.userRequest.callbackUrl;
+  return callbackUrl && callbackUrl.trim() !== '' ? callbackUrl : null;
+}
+
+/**
+ * Checks if payload has a callback URL
+ * 
+ * @param payload - Validated KakaoSkillPayload
+ * @returns true if callbackUrl is present and non-empty
+ */
+export function hasCallbackUrl(payload: KakaoSkillPayload): boolean {
+  return getCallbackUrl(payload) !== null;
+}

package/extensions/kakao-talkchannel/src/kakao/response.ts

@@ -0,0 +1,373 @@
+/**
+ * Kakao SkillResponse Builder
+ *
+ * Builds v2.0 format responses for Kakao Channel Plugin.
+ * Handles text chunking for 500-char visible limit (1000 char total).
+ *
+ * Reference: docs/relay-server-api-spec.md
+ */
+
+import type {
+  KakaoSkillResponse,
+  KakaoOutput,
+  KakaoThumbnail,
+  KakaoButton,
+  KakaoListItem,
+  KakaoItemListItem,
+  KakaoBasicCard,
+  KakaoTextCard,
+  KakaoCommerceCard,
+  KakaoListCard,
+  KakaoItemCard,
+} from "../types.js";
+
+/**
+ * Strip markdown formatting from text for Kakao (which doesn't support markdown)
+ *
+ * Handles:
+ * - Headers (# ## ### etc.)
+ * - Bold (**text** or __text__)
+ * - Italic (*text* or _text_)
+ * - Strikethrough (~~text~~)
+ * - Code blocks (```code``` and `inline code`)
+ * - Links ([text](url)) -> text (url)
+ * - Images (![alt](url)) -> [이미지: alt]
+ * - Blockquotes (> text)
+ * - Horizontal rules (--- or ***)
+ * - List markers (* - + and numbered lists)
+ *
+ * @param text - Text with potential markdown formatting
+ * @returns Plain text with markdown stripped
+ */
+export function stripMarkdown(text: string): string {
+  if (!text) return text;
+
+  let result = text;
+
+  // Remove code blocks first (```lang\ncode\n```)
+  result = result.replace(/```[\s\S]*?```/g, (match) => {
+    const content = match.replace(/```\w*\n?/g, "").replace(/```$/g, "");
+    return content.trim();
+  });
+
+  // Remove inline code (`code`)
+  result = result.replace(/`([^`]+)`/g, "$1");
+
+  // Convert images ![alt](url) -> [이미지: alt]
+  result = result.replace(/!\[([^\]]*)\]\([^)]+\)/g, "[이미지: $1]");
+
+  // Convert links [text](url) -> text (url)
+  result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)");
+
+  // Remove headers (# ## ### etc.) - keep the text
+  result = result.replace(/^#{1,6}\s+/gm, "");
+
+  // Remove bold (**text** or __text__)
+  result = result.replace(/\*\*([^*]+)\*\*/g, "$1");
+  result = result.replace(/__([^_]+)__/g, "$1");
+
+  // Remove italic (*text* or _text_) - avoid matching list items at line start
+  result = result.replace(/(?<!\n|\*)\*([^*\n]+)\*(?!\*)/g, "$1");
+  result = result.replace(/(?<!\n|_)_([^_\n]+)_(?!_)/g, "$1");
+
+  // Remove strikethrough (~~text~~)
+  result = result.replace(/~~([^~]+)~~/g, "$1");
+
+  // Remove blockquotes (> text) - keep the text
+  result = result.replace(/^>\s?/gm, "");
+
+  // Remove horizontal rules (---, ***, ___)
+  result = result.replace(/^[-*_]{3,}\s*$/gm, "");
+
+  // Clean up list markers at line start, preserve content
+  // Unordered lists: * - +
+  result = result.replace(/^[\s]*[-*+]\s+/gm, "• ");
+
+  // Ordered lists: 1. 2. etc.
+  result = result.replace(/^[\s]*\d+\.\s+/gm, "");
+
+  // Clean up multiple consecutive newlines
+  result = result.replace(/\n{3,}/g, "\n\n");
+
+  // Trim whitespace
+  result = result.trim();
+
+  return result;
+}
+
+/**
+ * Build v2.0 response with simpleText output
+ *
+ * @param text - Text content to send
+ * @returns KakaoSkillResponse with simpleText template
+ */
+export function buildSimpleTextResponse(text: string): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ simpleText: { text } }],
+    },
+  };
+}
+
+/**
+ * Build callback acknowledgment response
+ *
+ * Used when processing will take longer than 5 seconds.
+ * Tells Kakao to wait for callback via callbackUrl.
+ *
+ * @returns KakaoSkillResponse with useCallback flag
+ */
+export function buildCallbackAckResponse(): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    useCallback: true,
+  };
+}
+
+/**
+ * Build error response
+ *
+ * @param message - Error message to display to user
+ * @returns KakaoSkillResponse with error message
+ */
+export function buildErrorResponse(message: string): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ simpleText: { text: message } }],
+    },
+  };
+}
+
+export type ChunkMode = "sentence" | "newline" | "length";
+
+const DEFAULT_CHUNK_LIMIT = 400;
+
+function chunkBySentence(text: string, limit: number): string[] {
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= limit) {
+      chunks.push(remaining);
+      break;
+    }
+
+    const substring = remaining.substring(0, limit);
+    const lastSentenceEnd = Math.max(
+      substring.lastIndexOf("."),
+      substring.lastIndexOf("!"),
+      substring.lastIndexOf("?")
+    );
+
+    if (lastSentenceEnd > 0) {
+      chunks.push(remaining.substring(0, lastSentenceEnd + 1));
+      remaining = remaining.substring(lastSentenceEnd + 1).trim();
+    } else {
+      chunks.push(remaining.substring(0, limit));
+      remaining = remaining.substring(limit).trim();
+    }
+  }
+
+  return chunks;
+}
+
+function chunkByNewline(text: string, limit: number): string[] {
+  const paragraphs = text.split(/\n\s*\n/);
+  const chunks: string[] = [];
+  let currentChunk = "";
+
+  for (const paragraph of paragraphs) {
+    const trimmed = paragraph.trim();
+    if (!trimmed) continue;
+
+    if (currentChunk.length === 0) {
+      if (trimmed.length <= limit) {
+        currentChunk = trimmed;
+      } else {
+        chunks.push(...chunkBySentence(trimmed, limit));
+      }
+    } else if (currentChunk.length + 2 + trimmed.length <= limit) {
+      currentChunk += "\n\n" + trimmed;
+    } else {
+      chunks.push(currentChunk);
+      if (trimmed.length <= limit) {
+        currentChunk = trimmed;
+      } else {
+        chunks.push(...chunkBySentence(trimmed, limit));
+        currentChunk = "";
+      }
+    }
+  }
+
+  if (currentChunk) {
+    chunks.push(currentChunk);
+  }
+
+  return chunks;
+}
+
+function chunkByLength(text: string, limit: number): string[] {
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= limit) {
+      chunks.push(remaining);
+      break;
+    }
+    chunks.push(remaining.substring(0, limit));
+    remaining = remaining.substring(limit);
+  }
+
+  return chunks;
+}
+
+export function chunkTextForKakao(
+  text: string,
+  limit: number = DEFAULT_CHUNK_LIMIT,
+  mode: ChunkMode = "sentence"
+): string[] {
+  if (!text || text.length <= limit) {
+    return [text];
+  }
+
+  switch (mode) {
+    case "newline":
+      return chunkByNewline(text, limit);
+    case "length":
+      return chunkByLength(text, limit);
+    case "sentence":
+    default:
+      return chunkBySentence(text, limit);
+  }
+}
+
+export function buildMultiTextResponse(texts: string[]): KakaoSkillResponse {
+  const outputs: KakaoOutput[] = texts.slice(0, 3).map((text) => ({
+    simpleText: { text },
+  }));
+
+  return {
+    version: "2.0",
+    template: { outputs },
+  };
+}
+
+export function buildSimpleImageResponse(
+  imageUrl: string,
+  altText?: string
+): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ simpleImage: { imageUrl, altText } }],
+    },
+  };
+}
+
+export function buildTextCardResponse(
+  options: KakaoTextCard["textCard"]
+): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ textCard: options }],
+    },
+  };
+}
+
+export function buildBasicCardResponse(
+  options: KakaoBasicCard["basicCard"]
+): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ basicCard: options }],
+    },
+  };
+}
+
+export function buildCommerceCardResponse(
+  options: KakaoCommerceCard["commerceCard"]
+): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ commerceCard: options }],
+    },
+  };
+}
+
+export function buildListCardResponse(
+  header: KakaoListItem,
+  items: KakaoListItem[],
+  buttons?: KakaoButton[]
+): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ listCard: { header, items: items.slice(0, 5), buttons } }],
+    },
+  };
+}
+
+export function buildItemCardResponse(
+  options: KakaoItemCard["itemCard"]
+): KakaoSkillResponse {
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ itemCard: options }],
+    },
+  };
+}
+
+export function buildCarouselResponse(
+  type: "basicCard" | "commerceCard" | "itemCard" | "textCard",
+  items: KakaoOutput[]
+): KakaoSkillResponse {
+  const carouselItems = items.slice(0, 10).map((item, index) => {
+    const itemType = "basicCard" in item ? "basicCard"
+      : "commerceCard" in item ? "commerceCard"
+      : "itemCard" in item ? "itemCard"
+      : "textCard" in item ? "textCard"
+      : null;
+
+    if (!itemType) {
+      throw new Error(`Invalid carousel item at index ${index}: expected card type`);
+    }
+
+    if (itemType !== type) {
+      throw new Error(
+        `Carousel type mismatch at index ${index}: expected '${type}' but got '${itemType}'`
+      );
+    }
+
+    if ("basicCard" in item) return item.basicCard;
+    if ("commerceCard" in item) return item.commerceCard;
+    if ("itemCard" in item) return item.itemCard;
+    if ("textCard" in item) return item.textCard;
+    throw new Error(`Unreachable`);
+  });
+
+  return {
+    version: "2.0",
+    template: {
+      outputs: [{ carousel: { type, items: carouselItems } }],
+    },
+  };
+}
+
+export type {
+  KakaoThumbnail,
+  KakaoButton,
+  KakaoListItem,
+  KakaoItemListItem,
+  KakaoBasicCard,
+  KakaoTextCard,
+  KakaoCommerceCard,
+  KakaoListCard,
+  KakaoItemCard,
+};