@rscc/common-core 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -23,6 +23,10 @@ __export(index_exports, {
   ApiError: () => ApiError,
   BulkheadFullError: () => BulkheadFullError,
   CircuitOpenError: () => CircuitOpenError,
+  DEFAULT_CSRF_COOKIE_NAME: () => DEFAULT_CSRF_COOKIE_NAME,
+  DEFAULT_CSRF_HEADER_NAME: () => DEFAULT_CSRF_HEADER_NAME,
+  FIXED_MESSAGE_KEYS: () => FIXED_MESSAGE_KEYS,
+  MESSAGES: () => MESSAGES,
   ResultCode: () => ResultCode,
   WEBHOOK_SIGNATURE_HEADER: () => WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount: () => abbreviateAmount,
@@ -40,18 +44,26 @@ __export(index_exports, {
   createBusinessDays: () => createBusinessDays,
   createCircuitBreaker: () => createCircuitBreaker,
   createFeatureFlags: () => createFeatureFlags,
+  createSseEventParser: () => createSseEventParser,
   createTokenBucket: () => createTokenBucket,
   createTtlCache: () => createTtlCache,
+  csrfHeaderFor: () => csrfHeaderFor,
   decodeJwtPayload: () => decodeJwtPayload,
   decomposeHangul: () => decomposeHangul,
+  formatMessage: () => formatMessage,
   formatPhoneNumber: () => formatPhoneNumber,
+  formatSseComment: () => formatSseComment,
+  formatSseEvent: () => formatSseEvent,
   generateIdempotencyKey: () => generateIdempotencyKey,
+  getMessage: () => getMessage,
   getTokenExpiry: () => getTokenExpiry,
   isBulkResult: () => isBulkResult,
   isChosungQuery: () => isChosungQuery,
+  isCommonResultCode: () => isCommonResultCode,
   isForeignerRrn: () => isForeignerRrn,
   isRetryableStatus: () => isRetryableStatus,
   isTokenExpired: () => isTokenExpired,
+  isUnsafeMethod: () => isUnsafeMethod,
   isValidBusinessNumber: () => isValidBusinessNumber,
   isValidCorporateNumber: () => isValidCorporateNumber,
   isValidRrn: () => isValidRrn,
@@ -63,15 +75,22 @@ __export(index_exports, {
   maskPhone: () => maskPhone,
   maskSecret: () => maskSecret,
   matchesHangul: () => matchesHangul,
+  negotiateLanguage: () => negotiateLanguage,
   normalizeBusinessNumber: () => normalizeBusinessNumber,
   normalizePhoneNumber: () => normalizePhoneNumber,
   normalizeRrn: () => normalizeRrn,
+  parseChatPayload: () => parseChatPayload,
   parseFlag: () => parseFlag,
   parseRetryAfterMs: () => parseRetryAfterMs,
+  parseSseEvents: () => parseSseEvents,
   parseSseFrame: () => parseSseFrame,
   parseWireDateTime: () => parseWireDateTime,
   pickJosa: () => pickJosa,
+  readCookie: () => readCookie,
+  readSseChatEvents: () => readSseChatEvents,
+  readSseEvents: () => readSseEvents,
   readSseStream: () => readSseStream,
+  resultCodeForStatus: () => resultCodeForStatus,
   retry: () => retry,
   rrnBirthDate: () => rrnBirthDate,
   rrnChecksumOkLegacy: () => rrnChecksumOkLegacy,
@@ -80,6 +99,7 @@ __export(index_exports, {
   sniffFile: () => sniffFile,
   stripZone: () => stripZone,
   toChosung: () => toChosung,
+  toCommonResultCode: () => toCommonResultCode,
   toE164: () => toE164,
   toFormalNotation: () => toFormalNotation,
   toKoreanWords: () => toKoreanWords,
@@ -112,6 +132,108 @@ var ResultCode = {
   INTERNAL_SERVER_ERROR: "500"
 };
 
+// src/errorCodes.ts
+var COMMON_CODES = new Set(Object.values(ResultCode));
+function isCommonResultCode(code) {
+  return COMMON_CODES.has(code);
+}
+function resultCodeForStatus(status) {
+  const exact = String(status);
+  if (exact !== ResultCode.SUCCESS && COMMON_CODES.has(exact)) return exact;
+  if (status >= 400 && status < 500) return ResultCode.BAD_REQUEST;
+  return ResultCode.INTERNAL_SERVER_ERROR;
+}
+function toCommonResultCode(code, status) {
+  return isCommonResultCode(code) ? code : resultCodeForStatus(status);
+}
+
+// src/csrf.ts
+var DEFAULT_CSRF_COOKIE_NAME = "XSRF-TOKEN";
+var DEFAULT_CSRF_HEADER_NAME = "X-XSRF-TOKEN";
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS", "TRACE"]);
+var SENTINEL_ORIGIN = "http://rscc-csrf.invalid";
+var ABSOLUTE_URL = /^([a-zA-Z][a-zA-Z\d+.-]*):\/\/([^/?#\\]*)/;
+var HAS_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
+var PROTOCOL_RELATIVE = /^[\\/]{2}/;
+var DEFAULT_PORTS = { http: "80", https: "443", ws: "80", wss: "443" };
+function readCookie(name, cookieString) {
+  const source = cookieString ?? documentCookie();
+  if (!source) return null;
+  for (const part of source.split(";")) {
+    const pair = part.trim();
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    if (pair.slice(0, eq) === name) return pair.slice(eq + 1);
+  }
+  return null;
+}
+function isUnsafeMethod(method) {
+  return !SAFE_METHODS.has((method || "GET").toUpperCase());
+}
+function csrfHeaderFor(url, method, options) {
+  if (!isUnsafeMethod(method)) return null;
+  const opts = options === true || options === void 0 ? {} : options;
+  const cookieString = opts.readCookie ? opts.readCookie() : documentCookie();
+  if (!cookieString) return null;
+  const token = readCookie(opts.cookieName ?? DEFAULT_CSRF_COOKIE_NAME, cookieString);
+  if (!token) return null;
+  if (!isAllowedTarget(url, opts.allowedOrigins)) return null;
+  return [opts.headerName ?? DEFAULT_CSRF_HEADER_NAME, token];
+}
+function documentCookie() {
+  if (typeof document === "undefined") return null;
+  try {
+    return typeof document.cookie === "string" ? document.cookie : null;
+  } catch {
+    return null;
+  }
+}
+function currentLocation() {
+  if (typeof location === "undefined") return null;
+  try {
+    const { href, origin } = location;
+    return typeof href === "string" && typeof origin === "string" ? { href, origin } : null;
+  } catch {
+    return null;
+  }
+}
+function isAllowedTarget(url, allowedOrigins) {
+  const loc = currentLocation();
+  const base = loc ? loc.href : SENTINEL_ORIGIN;
+  const selfOrigin = loc ? loc.origin : SENTINEL_ORIGIN;
+  const target = originOf(url, base, selfOrigin);
+  if (target === null || target === "null") return false;
+  if (selfOrigin !== "null" && target === selfOrigin) return true;
+  if (!allowedOrigins || allowedOrigins.length === 0) return false;
+  return allowedOrigins.some((entry) => originOf(entry, base, selfOrigin) === target);
+}
+function originOf(url, base, baseOrigin) {
+  try {
+    if (typeof URL === "function") {
+      const origin = new URL(url, base).origin;
+      if (typeof origin === "string") return origin;
+    }
+  } catch {
+  }
+  return looseOriginOf(url, baseOrigin);
+}
+function looseOriginOf(url, baseOrigin) {
+  const trimmed = url.trim();
+  const m = ABSOLUTE_URL.exec(trimmed);
+  if (m) {
+    const scheme = m[1].toLowerCase();
+    const authority = m[2];
+    const hostPort = authority.slice(authority.lastIndexOf("@") + 1).toLowerCase();
+    const hp = /^(.*?)(?::(\d*))?$/.exec(hostPort);
+    const host = hp?.[1] ?? "";
+    const port = hp?.[2] ?? "";
+    if (!host) return null;
+    return port === "" || port === DEFAULT_PORTS[scheme] ? `${scheme}://${host}` : `${scheme}://${host}:${port}`;
+  }
+  if (PROTOCOL_RELATIVE.test(trimmed) || HAS_SCHEME.test(trimmed)) return null;
+  return baseOrigin;
+}
+
 // src/idempotency.ts
 var FALLBACK_GROUPS = [8, 4, 4, 4, 12];
 function generateIdempotencyKey() {
@@ -124,6 +246,141 @@ function generateIdempotencyKey() {
   }).join("-");
 }
 
+// src/messages.ts
+var KO = Object.freeze({
+  "rscc.result.SUCCESS": "\uC694\uCCAD\uC774 \uC131\uACF5\uC801\uC73C\uB85C \uCC98\uB9AC\uB418\uC5C8\uC2B5\uB2C8\uB2E4.",
+  "rscc.result.BAD_REQUEST": "\uC798\uBABB\uB41C \uC694\uCCAD\uC785\uB2C8\uB2E4.",
+  "rscc.result.UNAUTHORIZED": "\uC778\uC99D\uB418\uC9C0 \uC54A\uC740 \uC0AC\uC6A9\uC790\uC785\uB2C8\uB2E4.",
+  "rscc.result.FORBIDDEN": "\uC811\uADFC \uAD8C\uD55C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  "rscc.result.NOT_FOUND": "\uB9AC\uC18C\uC2A4\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  "rscc.result.METHOD_NOT_ALLOWED": "\uD5C8\uC6A9\uB418\uC9C0 \uC54A\uC740 \uC694\uCCAD \uBC29\uC2DD\uC785\uB2C8\uB2E4.",
+  "rscc.result.CONFLICT": "\uC774\uBBF8 \uC874\uC7AC\uD558\uB294 \uB9AC\uC18C\uC2A4\uC785\uB2C8\uB2E4.",
+  "rscc.result.UNSUPPORTED_MEDIA_TYPE": "\uC9C0\uC6D0\uD558\uC9C0 \uC54A\uB294 \uC694\uCCAD \uD615\uC2DD\uC785\uB2C8\uB2E4.",
+  "rscc.result.TOO_MANY_REQUESTS": "\uC694\uCCAD \uD55C\uB3C4\uB97C \uCD08\uACFC\uD588\uC2B5\uB2C8\uB2E4.",
+  "rscc.result.INTERNAL_SERVER_ERROR": "\uC11C\uBC84 \uB0B4\uBD80 \uC624\uB958\uAC00 \uBC1C\uC0DD\uD588\uC2B5\uB2C8\uB2E4.",
+  "rscc.web.missingParameter": "\uD544\uC218 \uC694\uCCAD \uD30C\uB77C\uBBF8\uD130\uAC00 \uB204\uB77D\uB418\uC5C8\uC2B5\uB2C8\uB2E4: {0}",
+  "rscc.web.typeMismatch": "\uC694\uCCAD \uD30C\uB77C\uBBF8\uD130 \uD0C0\uC785\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4: {0}",
+  "rscc.web.unreadableBody": "\uC694\uCCAD \uBCF8\uBB38\uC744 \uD574\uC11D\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. JSON \uD615\uC2DD\uACFC \uAC01 \uD544\uB4DC\uC758 \uD0C0\uC785\uC744 \uD655\uC778\uD558\uC138\uC694.",
+  "rscc.idempotency.conflict": "\uC774\uBBF8 \uCC98\uB9AC\uB418\uC5C8\uAC70\uB098 \uCC98\uB9AC \uC911\uC778 \uC694\uCCAD\uC785\uB2C8\uB2E4.",
+  "rscc.idempotency.invalidFormat": "Idempotency-Key \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+  "rscc.idempotency.required": "Idempotency-Key \uD5E4\uB354\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  "rscc.upload.size": "\uC5C5\uB85C\uB4DC \uAC00\uB2A5\uD55C \uCD5C\uB300 \uD06C\uAE30\uB97C \uCD08\uACFC\uD588\uC2B5\uB2C8\uB2E4.",
+  "rscc.upload.extension": "\uD5C8\uC6A9\uB418\uC9C0 \uC54A\uB294 \uD30C\uC77C \uD615\uC2DD\uC785\uB2C8\uB2E4: {0}",
+  "rscc.upload.contentMismatch": "\uD30C\uC77C \uB0B4\uC6A9\uC774 \uD655\uC7A5\uC790\uC640 \uC77C\uCE58\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+  "rscc.query.sortField": "\uC815\uB82C\uD560 \uC218 \uC5C6\uB294 \uD544\uB4DC\uC785\uB2C8\uB2E4: {0}",
+  "rscc.query.sortDirection": "\uC815\uB82C \uBC29\uD5A5\uC740 asc|desc \uB9CC \uD5C8\uC6A9\uD569\uB2C8\uB2E4: {0}",
+  "rscc.security.csrf": "CSRF \uD1A0\uD070\uC774 \uC5C6\uAC70\uB098 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+  "rscc.client.unreadableBody": "\uC751\uB2F5 \uBCF8\uBB38\uC744 \uC77D\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4.",
+  "rscc.client.invalidJson": "\uC751\uB2F5 \uBCF8\uBB38\uC774 \uC720\uD6A8\uD55C JSON \uC774 \uC544\uB2D9\uB2C8\uB2E4.",
+  "rscc.client.httpError": "API \uC624\uB958: {0} {1}"
+});
+var EN = Object.freeze({
+  "rscc.result.SUCCESS": "The request was processed successfully.",
+  "rscc.result.BAD_REQUEST": "Bad request.",
+  "rscc.result.UNAUTHORIZED": "Authentication is required.",
+  "rscc.result.FORBIDDEN": "Access is denied.",
+  "rscc.result.NOT_FOUND": "Resource not found.",
+  "rscc.result.METHOD_NOT_ALLOWED": "Request method is not allowed.",
+  "rscc.result.CONFLICT": "The resource already exists.",
+  "rscc.result.UNSUPPORTED_MEDIA_TYPE": "Unsupported request content type.",
+  "rscc.result.TOO_MANY_REQUESTS": "Too many requests.",
+  "rscc.result.INTERNAL_SERVER_ERROR": "An internal server error occurred.",
+  "rscc.web.missingParameter": "Required request parameter is missing: {0}",
+  "rscc.web.typeMismatch": "Request parameter has an invalid type: {0}",
+  "rscc.web.unreadableBody": "The request body could not be read. Check the JSON syntax and field types.",
+  "rscc.idempotency.conflict": "The request has already been processed or is in progress.",
+  "rscc.idempotency.invalidFormat": "Invalid Idempotency-Key format.",
+  "rscc.idempotency.required": "The Idempotency-Key header is required.",
+  "rscc.upload.size": "The upload exceeds the maximum allowed size.",
+  "rscc.upload.extension": "File type is not allowed: {0}",
+  "rscc.upload.contentMismatch": "File content does not match its extension.",
+  "rscc.query.sortField": "Field cannot be sorted: {0}",
+  "rscc.query.sortDirection": "Sort direction must be asc or desc: {0}",
+  "rscc.security.csrf": "The CSRF token is missing or invalid.",
+  "rscc.client.unreadableBody": "Failed to read the response body.",
+  "rscc.client.invalidJson": "The response body is not valid JSON.",
+  "rscc.client.httpError": "API error: {0} {1}"
+});
+var MESSAGES = Object.freeze({ ko: KO, en: EN });
+var FIXED_KEY_LIST = [
+  "rscc.idempotency.conflict",
+  "rscc.idempotency.invalidFormat",
+  "rscc.idempotency.required",
+  "rscc.query.sortField",
+  "rscc.query.sortDirection",
+  "rscc.security.csrf"
+];
+var FIXED_KEYS = new Set(FIXED_KEY_LIST);
+var FIXED_MESSAGE_KEYS = new Set(FIXED_KEY_LIST);
+var PLACEHOLDER = /\{(\d+)\}/g;
+function formatMessage(template, ...args) {
+  if (args.length === 0) return template;
+  return template.replace(PLACEHOLDER, (match, digits) => {
+    const index = Number(digits);
+    return index < args.length ? String(args[index]) : match;
+  });
+}
+function primarySubtag(tag) {
+  if (tag === void 0) return "";
+  const trimmed = tag.trim();
+  const dash = trimmed.indexOf("-");
+  return (dash < 0 ? trimmed : trimmed.slice(0, dash)).toLowerCase();
+}
+function builtinCatalog(language) {
+  return language === "ko" || language === "en" ? MESSAGES[language] : void 0;
+}
+function lookupBuiltin(language, key) {
+  const catalog = builtinCatalog(language);
+  return catalog !== void 0 && Object.prototype.hasOwnProperty.call(catalog, key) ? catalog[key] : void 0;
+}
+function lookupOverride(overrides, key, language) {
+  if (overrides === void 0) return void 0;
+  const value = typeof overrides === "function" ? overrides(key, language) : Object.prototype.hasOwnProperty.call(overrides, key) ? overrides[key] : void 0;
+  return typeof value === "string" && value !== "" && value !== key ? value : void 0;
+}
+function getMessage(key, options = {}) {
+  const defaultLanguage = primarySubtag(options.defaultLocale) || "ko";
+  const language = primarySubtag(options.locale) || defaultLanguage;
+  const args = options.args ?? [];
+  const template = (FIXED_KEYS.has(key) && (language === "ko" || language === "en") ? lookupBuiltin(language, key) : void 0) ?? lookupOverride(options.overrides, key, language) ?? lookupBuiltin(language, key) ?? lookupBuiltin(defaultLanguage, key) ?? lookupBuiltin("ko", key) ?? key;
+  return formatMessage(template, ...args);
+}
+var LANGUAGE_RANGE = /^(?:\*|[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8})*)$/;
+var Q_VALUE = /^(?:\d+(?:\.\d*)?|\.\d+)$/;
+function negotiateLanguage(acceptLanguage, supported = ["ko", "en"], fallback = "ko") {
+  if (acceptLanguage == null || acceptLanguage.trim() === "") return fallback;
+  const supportedSet = new Set(supported.map((s) => primarySubtag(s)).filter((s) => s !== ""));
+  const ranges = [];
+  for (const item of acceptLanguage.split(",")) {
+    const [rawTag = "", ...params] = item.split(";");
+    const tag = rawTag.trim();
+    if (!LANGUAGE_RANGE.test(tag)) continue;
+    let q = 1;
+    let valid = true;
+    for (const param of params) {
+      const eq = param.indexOf("=");
+      const name = (eq < 0 ? param : param.slice(0, eq)).trim().toLowerCase();
+      if (name !== "q") continue;
+      const value = eq < 0 ? "" : param.slice(eq + 1).trim();
+      const parsed = Number(value);
+      if (!Q_VALUE.test(value) || parsed < 0 || parsed > 1) {
+        valid = false;
+        break;
+      }
+      q = parsed;
+    }
+    if (!valid || q === 0) continue;
+    ranges.push({ tag, q });
+  }
+  ranges.sort((a, b) => b.q - a.q);
+  for (const { tag } of ranges) {
+    if (tag === "*") return fallback;
+    const language = primarySubtag(tag);
+    if (supportedSet.has(language)) return language;
+  }
+  return fallback;
+}
+
 // src/retry.ts
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
 function isRetryableStatus(status) {
@@ -209,6 +466,7 @@ var ApiError = class extends Error {
     super(args.message);
     this.name = "ApiError";
     this.code = args.code;
+    this.commonCode = toCommonResultCode(args.code, args.status);
     this.status = args.status;
     this.traceId = args.traceId;
     this.data = args.data;
@@ -240,6 +498,8 @@ function isCommonResponse(value) {
 }
 function createApiClient(config) {
   const traceIdHeader = config.traceIdHeader ?? "X-Trace-Id";
+  const clientMessage = (key, ...args) => getMessage(key, { locale: config.locale, args });
+  const acceptLanguage = config.sendAcceptLanguage && config.locale && config.locale.trim() !== "" ? config.locale.trim() : null;
   let hookWarned = false;
   const safeHook = (fn) => {
     try {
@@ -255,6 +515,8 @@ function createApiClient(config) {
   async function requestWithMeta(path, init = {}) {
     const sentTraceId = generateTraceId();
     const method = (init.method ?? "GET").toUpperCase();
+    const url = joinUrl(config.baseUrl, path);
+    const credentials = init.credentials ?? config.credentials;
     const idempotencyHeader = config.idempotency?.header ?? "Idempotency-Key";
     const idempotencyKey = config.idempotency && (config.idempotency.methods ?? DEFAULT_IDEMPOTENCY_METHODS).includes(method) ? generateIdempotencyKey() : null;
     const attemptOnce = async () => {
@@ -266,12 +528,23 @@ function createApiClient(config) {
       if (!headers.has("Content-Type") && typeof init.body === "string") {
         headers.set("Content-Type", "application/json");
       }
+      if (acceptLanguage !== null && !headers.has("Accept-Language")) {
+        headers.set("Accept-Language", acceptLanguage);
+      }
       if (config.getToken && !headers.has("Authorization")) {
         const token = config.getToken();
         if (token) headers.set("Authorization", `Bearer ${token}`);
       }
+      if (config.csrf) {
+        const csrfHeader = csrfHeaderFor(url, method, config.csrf);
+        if (csrfHeader && !headers.has(csrfHeader[0])) headers.set(csrfHeader[0], csrfHeader[1]);
+      }
       const fetchFn = config.fetchImpl ?? globalThis.fetch;
-      const response = await fetchFn(joinUrl(config.baseUrl, path), { ...init, headers });
+      const response = await fetchFn(url, {
+        ...init,
+        ...credentials !== void 0 ? { credentials } : {},
+        headers
+      });
       const traceId = response.headers.get(traceIdHeader) ?? sentTraceId;
       let raw = null;
       try {
@@ -281,7 +554,7 @@ function createApiClient(config) {
         if (config.strictJson && response.ok) {
           throw new ApiError({
             code: "INVALID_JSON",
-            message: "\uC751\uB2F5 \uBCF8\uBB38\uC744 \uC77D\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4.",
+            message: clientMessage("rscc.client.unreadableBody"),
             status: response.status,
             traceId,
             retryAfterMs: parseRetryAfterMs(response.headers.get("Retry-After"))
@@ -300,7 +573,7 @@ function createApiClient(config) {
             if (config.strictJson && response.ok) {
               throw new ApiError({
                 code: "INVALID_JSON",
-                message: "\uC751\uB2F5 \uBCF8\uBB38\uC774 \uC720\uD6A8\uD55C JSON \uC774 \uC544\uB2D9\uB2C8\uB2E4.",
+                message: clientMessage("rscc.client.invalidJson"),
                 status: response.status,
                 traceId,
                 retryAfterMs: parseRetryAfterMs(response.headers.get("Retry-After")),
@@ -329,7 +602,7 @@ function createApiClient(config) {
       }
       if (!response.ok) {
         const j2 = json;
-        const message = typeof j2?.message === "string" && j2.message || typeof j2?.error === "string" && j2.error || `API \uC624\uB958: ${response.status} ${response.statusText}`;
+        const message = typeof j2?.message === "string" && j2.message || typeof j2?.error === "string" && j2.error || clientMessage("rscc.client.httpError", response.status, response.statusText);
         fail(String(response.status), message);
       }
       return { data: json, traceId, status: response.status, response };
@@ -387,13 +660,232 @@ function createApiClient(config) {
   return { request, requestWithMeta };
 }
 
+// src/sseEvents.ts
+var RETRY_PATTERN = /^[0-9]+$/;
+function createParser(onEvent, onRetry, haltOnTrue, initialLastEventId) {
+  let pending = "";
+  let bomChecked = false;
+  let skipLeadingLf = false;
+  let data = "";
+  let eventType = "";
+  let idBuffer = initialLastEventId;
+  let lastEventId = initialLastEventId;
+  let retryMs = null;
+  let ended = false;
+  let halted = false;
+  const lineBreak = /[\r\n]/g;
+  const dispatch = () => {
+    lastEventId = idBuffer;
+    if (data === "") {
+      eventType = "";
+      return;
+    }
+    const event = {
+      event: eventType === "" ? "message" : eventType,
+      data: data.endsWith("\n") ? data.slice(0, -1) : data,
+      id: lastEventId
+    };
+    data = "";
+    eventType = "";
+    if (onEvent(event) === true && haltOnTrue) halted = true;
+  };
+  const processLine = (line) => {
+    if (line === "") {
+      dispatch();
+      return;
+    }
+    if (line.charCodeAt(0) === 58) return;
+    const colon = line.indexOf(":");
+    let field;
+    let value;
+    if (colon === -1) {
+      field = line;
+      value = "";
+    } else {
+      field = line.slice(0, colon);
+      value = line.slice(colon + 1);
+      if (value.charCodeAt(0) === 32) value = value.slice(1);
+    }
+    switch (field) {
+      case "event":
+        eventType = value;
+        break;
+      case "data":
+        data += value + "\n";
+        break;
+      case "id":
+        if (!value.includes("\0")) idBuffer = value;
+        break;
+      case "retry":
+        if (RETRY_PATTERN.test(value)) {
+          retryMs = Number(value);
+          onRetry?.(retryMs);
+        }
+        break;
+      default:
+        break;
+    }
+  };
+  const feed = (chunk) => {
+    if (ended) throw new Error("SSE \uD30C\uC11C\uAC00 \uC774\uBBF8 \uC885\uB8CC\uB418\uC5C8\uC2B5\uB2C8\uB2E4(end \uC774\uD6C4 feed).");
+    if (halted || chunk === "") return;
+    let text = chunk;
+    if (!bomChecked) {
+      bomChecked = true;
+      if (text.charCodeAt(0) === 65279) text = text.slice(1);
+    }
+    if (skipLeadingLf) {
+      skipLeadingLf = false;
+      if (text.charCodeAt(0) === 10) text = text.slice(1);
+    }
+    let start = 0;
+    for (; ; ) {
+      lineBreak.lastIndex = start;
+      const match = lineBreak.exec(text);
+      if (match === null) break;
+      const at = match.index;
+      const line = pending + text.slice(start, at);
+      pending = "";
+      let next = at + 1;
+      if (text.charCodeAt(at) === 13) {
+        if (next < text.length) {
+          if (text.charCodeAt(next) === 10) next += 1;
+        } else {
+          skipLeadingLf = true;
+        }
+      }
+      start = next;
+      processLine(line);
+      if (halted) return;
+    }
+    pending += text.slice(start);
+  };
+  const end = (options) => {
+    if (ended) return;
+    ended = true;
+    if (halted) return;
+    if (options?.dispatchIncomplete) {
+      if (pending !== "") processLine(pending);
+      if (!halted) dispatch();
+    }
+    pending = "";
+    data = "";
+    eventType = "";
+  };
+  return {
+    feed,
+    end,
+    get lastEventId() {
+      return lastEventId;
+    },
+    get retryMs() {
+      return retryMs;
+    }
+  };
+}
+function createSseEventParser(onEvent, onRetry, options) {
+  return createParser(onEvent, onRetry, false, options?.lastEventId ?? "");
+}
+function parseSseEvents(text) {
+  const events = [];
+  const parser = createSseEventParser((e) => {
+    events.push(e);
+  });
+  parser.feed(text);
+  parser.end();
+  return events;
+}
+async function readSseEvents(response, options) {
+  if (!response.body) {
+    throw new Error("SSE \uC751\uB2F5\uC5D0 body \uC2A4\uD2B8\uB9BC\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+  let stopped = false;
+  const parser = createParser(
+    (event) => {
+      if (options.onEvent(event) === true) {
+        stopped = true;
+        return true;
+      }
+      return void 0;
+    },
+    options.onRetry,
+    true,
+    options.lastEventId ?? ""
+  );
+  const result = () => ({
+    lastEventId: parser.lastEventId,
+    retryMs: parser.retryMs,
+    stopped
+  });
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      parser.feed(decoder.decode(value, { stream: true }));
+      if (stopped) {
+        await reader.cancel().catch(() => void 0);
+        return result();
+      }
+    }
+    parser.feed(decoder.decode());
+    parser.end({ dispatchIncomplete: options.dispatchIncompleteAtEof === true });
+    return result();
+  } catch (error) {
+    await reader.cancel(error).catch(() => void 0);
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+}
+var CR_OR_LF = /[\r\n]/;
+function formatSseEvent(data, options = {}) {
+  const { event, id, retry: retry2 } = options;
+  let out = "";
+  if (id !== void 0) {
+    if (CR_OR_LF.test(id) || id.includes("\0")) {
+      throw new Error("SSE id \uC5D0 CR\xB7LF\xB7NUL \uC744 \uB123\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    }
+    out += `id: ${id}
+`;
+  }
+  if (event !== void 0 && event !== "") {
+    if (CR_OR_LF.test(event)) throw new Error("SSE event \uC5D0 CR\xB7LF \uB97C \uB123\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    out += `event: ${event}
+`;
+  }
+  if (retry2 !== void 0) {
+    if (!Number.isSafeInteger(retry2) || retry2 < 0) {
+      throw new Error(`SSE retry \uB294 0 \uC774\uC0C1\uC758 \uC815\uC218(ms)\uC5EC\uC57C \uD569\uB2C8\uB2E4: ${retry2}`);
+    }
+    out += `retry: ${retry2}
+`;
+  }
+  for (const line of data.split(/\r\n|\r|\n/)) {
+    out += `data: ${line}
+`;
+  }
+  return out + "\n";
+}
+function formatSseComment(text = "") {
+  if (CR_OR_LF.test(text)) throw new Error("SSE \uC8FC\uC11D\uC5D0 CR\xB7LF \uB97C \uB123\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  return text === "" ? ":\n\n" : `: ${text}
+
+`;
+}
+
 // src/sse.ts
 function parseSseFrame(frame) {
   const dataLine = frame.split("\n").find((l) => l.startsWith("data:"))?.replace(/^data:\s*/, "");
-  if (dataLine === void 0 || dataLine === "") return { type: "skip" };
-  if (dataLine === "[DONE]") return { type: "done" };
+  if (dataLine === void 0) return { type: "skip" };
+  return parseChatPayload(dataLine);
+}
+function parseChatPayload(data) {
+  if (data === "") return { type: "skip" };
+  if (data === "[DONE]") return { type: "done" };
   try {
-    const obj = JSON.parse(dataLine);
+    const obj = JSON.parse(data);
     if (typeof obj.conversationId === "number") {
       return { type: "conversationId", id: obj.conversationId };
     }
@@ -406,16 +898,9 @@ function parseSseFrame(frame) {
   }
   return { type: "skip" };
 }
-async function readSseStream(response, callbacks) {
-  if (!response.body) {
-    throw new Error("SSE \uC751\uB2F5\uC5D0 body \uC2A4\uD2B8\uB9BC\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
-  }
-  const reader = response.body.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
+function createChatDispatcher(callbacks) {
   let errored = false;
-  const dispatch = (frame) => {
-    const ev = parseSseFrame(frame);
+  return (ev) => {
     switch (ev.type) {
       case "conversationId":
         callbacks.onConversationId?.(ev.id);
@@ -438,6 +923,16 @@ async function readSseStream(response, callbacks) {
     }
     return false;
   };
+}
+async function readSseStream(response, callbacks) {
+  if (!response.body) {
+    throw new Error("SSE \uC751\uB2F5\uC5D0 body \uC2A4\uD2B8\uB9BC\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const deliver = createChatDispatcher(callbacks);
+  const dispatch = (frame) => deliver(parseSseFrame(frame));
   try {
     while (true) {
       const { done, value } = await reader.read();
@@ -459,6 +954,14 @@ async function readSseStream(response, callbacks) {
     reader.releaseLock();
   }
 }
+async function readSseChatEvents(response, callbacks) {
+  const deliver = createChatDispatcher(callbacks);
+  await readSseEvents(response, {
+    onEvent: (event) => deliver(parseChatPayload(event.data.trim())),
+    // 레거시 readSseStream 의 EOF 잔여 버퍼 처리와 같게 — 미완성 이벤트도 디스패치
+    dispatchIncompleteAtEof: true
+  });
+}
 
 // src/jwt.ts
 function decodeJwtPayload(token) {
@@ -1090,25 +1593,22 @@ function extensionOf(fileName) {
   return fileName.slice(dot + 1).toLowerCase();
 }
 function validateUpload(input) {
+  const message = (key, ...args) => getMessage(key, { locale: input.locale, args, overrides: input.messages });
   if (input.size > input.maxSizeBytes) {
-    return { ok: false, reason: "size", message: "\uC5C5\uB85C\uB4DC \uAC00\uB2A5\uD55C \uCD5C\uB300 \uD06C\uAE30\uB97C \uCD08\uACFC\uD588\uC2B5\uB2C8\uB2E4." };
+    return { ok: false, reason: "size", message: message("rscc.upload.size") };
   }
   const ext = extensionOf(input.fileName);
   const allowed = input.allowedExtensions.map(
     (e) => (e.startsWith(".") ? e.slice(1) : e).toLowerCase()
   );
   if (ext === "" || !allowed.includes(ext)) {
-    return { ok: false, reason: "extension", message: `\uD5C8\uC6A9\uB418\uC9C0 \uC54A\uB294 \uD30C\uC77C \uD615\uC2DD\uC785\uB2C8\uB2E4: ${ext}` };
+    return { ok: false, reason: "extension", message: message("rscc.upload.extension", ext) };
   }
   const extra = input.extraMappings?.[ext];
   const kinds = extra !== void 0 ? new Set(extra) : kindsForExtension(ext);
   const kind = sniffFile(input.head);
   if (kind === null || !kinds.has(kind)) {
-    return {
-      ok: false,
-      reason: "content-mismatch",
-      message: "\uD30C\uC77C \uB0B4\uC6A9\uC774 \uD655\uC7A5\uC790\uC640 \uC77C\uCE58\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4."
-    };
+    return { ok: false, reason: "content-mismatch", message: message("rscc.upload.contentMismatch") };
   }
   return { ok: true };
 }
@@ -1779,6 +2279,10 @@ function matchesHangul(query, target) {
   ApiError,
   BulkheadFullError,
   CircuitOpenError,
+  DEFAULT_CSRF_COOKIE_NAME,
+  DEFAULT_CSRF_HEADER_NAME,
+  FIXED_MESSAGE_KEYS,
+  MESSAGES,
   ResultCode,
   WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount,
@@ -1796,18 +2300,26 @@ function matchesHangul(query, target) {
   createBusinessDays,
   createCircuitBreaker,
   createFeatureFlags,
+  createSseEventParser,
   createTokenBucket,
   createTtlCache,
+  csrfHeaderFor,
   decodeJwtPayload,
   decomposeHangul,
+  formatMessage,
   formatPhoneNumber,
+  formatSseComment,
+  formatSseEvent,
   generateIdempotencyKey,
+  getMessage,
   getTokenExpiry,
   isBulkResult,
   isChosungQuery,
+  isCommonResultCode,
   isForeignerRrn,
   isRetryableStatus,
   isTokenExpired,
+  isUnsafeMethod,
   isValidBusinessNumber,
   isValidCorporateNumber,
   isValidRrn,
@@ -1819,15 +2331,22 @@ function matchesHangul(query, target) {
   maskPhone,
   maskSecret,
   matchesHangul,
+  negotiateLanguage,
   normalizeBusinessNumber,
   normalizePhoneNumber,
   normalizeRrn,
+  parseChatPayload,
   parseFlag,
   parseRetryAfterMs,
+  parseSseEvents,
   parseSseFrame,
   parseWireDateTime,
   pickJosa,
+  readCookie,
+  readSseChatEvents,
+  readSseEvents,
   readSseStream,
+  resultCodeForStatus,
   retry,
   rrnBirthDate,
   rrnChecksumOkLegacy,
@@ -1836,6 +2355,7 @@ function matchesHangul(query, target) {
   sniffFile,
   stripZone,
   toChosung,
+  toCommonResultCode,
   toE164,
   toFormalNotation,
   toKoreanWords,