@rscc/common-core 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -25,6 +25,8 @@ __export(index_exports, {
   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,
@@ -42,16 +44,22 @@ __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,
@@ -67,16 +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,
@@ -85,6 +99,7 @@ __export(index_exports, {
   sniffFile: () => sniffFile,
   stripZone: () => stripZone,
   toChosung: () => toChosung,
+  toCommonResultCode: () => toCommonResultCode,
   toE164: () => toE164,
   toFormalNotation: () => toFormalNotation,
   toKoreanWords: () => toKoreanWords,
@@ -117,6 +132,21 @@ 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";
@@ -216,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) {
@@ -301,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;
@@ -332,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 {
@@ -360,6 +528,9 @@ 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}`);
@@ -383,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"))
@@ -402,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")),
@@ -431,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 };
@@ -489,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 };
     }
@@ -508,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);
@@ -540,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();
@@ -561,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) {
@@ -620,22 +1021,190 @@ function maskCardNumber(cardNumber) {
 
 // src/datetime.ts
 var pad = (n) => String(n).padStart(2, "0");
-function toWireDateTime(date) {
-  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+var zoneFormatters = /* @__PURE__ */ new Map();
+function zoneFormatter(timeZone) {
+  let formatter = zoneFormatters.get(timeZone);
+  if (formatter === void 0) {
+    formatter = new Intl.DateTimeFormat("en-US-u-ca-gregory-nu-latn", {
+      timeZone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit"
+    });
+    zoneFormatters.set(timeZone, formatter);
+  }
+  return formatter;
+}
+function zonedFields(ms, timeZone) {
+  const fields = {
+    year: 0,
+    month: 0,
+    day: 0,
+    hour: 0,
+    minute: 0,
+    second: 0,
+    millisecond: (ms % 1e3 + 1e3) % 1e3
+  };
+  for (const part of zoneFormatter(timeZone).formatToParts(ms)) {
+    switch (part.type) {
+      case "year":
+        fields.year = Number(part.value);
+        break;
+      case "month":
+        fields.month = Number(part.value);
+        break;
+      case "day":
+        fields.day = Number(part.value);
+        break;
+      case "hour":
+        fields.hour = Number(part.value) % 24;
+        break;
+      case "minute":
+        fields.minute = Number(part.value);
+        break;
+      case "second":
+        fields.second = Number(part.value);
+        break;
+      default:
+        break;
+    }
+  }
+  return fields;
+}
+function wallAsUtcMs(f) {
+  const d = /* @__PURE__ */ new Date(0);
+  d.setUTCFullYear(f.year, f.month - 1, f.day);
+  d.setUTCHours(f.hour, f.minute, f.second, f.millisecond);
+  return d.getTime();
+}
+function offsetMinutes(ms, timeZone) {
+  const wall = zonedFields(ms, timeZone);
+  wall.millisecond = 0;
+  return (wallAsUtcMs(wall) - Math.floor(ms / 1e3) * 1e3) / 6e4;
+}
+var DAY_MS = 864e5;
+function wallToEpoch(fields, timeZone) {
+  const wall = wallAsUtcMs(fields);
+  const toMs = (minutes) => Math.round(minutes * 6e4);
+  const before = offsetMinutes(wall - DAY_MS, timeZone);
+  const after = offsetMinutes(wall + DAY_MS, timeZone);
+  const atBefore = wall - toMs(before);
+  if (offsetMinutes(atBefore, timeZone) === before) return atBefore;
+  const atAfter = wall - toMs(after);
+  if (offsetMinutes(atAfter, timeZone) === after) return atAfter;
+  return atBefore;
+}
+function formatOffset(minutes) {
+  const totalSeconds = Math.round(minutes * 60);
+  if (totalSeconds === 0) return "Z";
+  const sign = totalSeconds < 0 ? "-" : "+";
+  const abs = Math.abs(totalSeconds);
+  const hh = pad(Math.floor(abs / 3600));
+  const mm = pad(Math.floor(abs % 3600 / 60));
+  const ss = abs % 60;
+  return `${sign}${hh}:${mm}${ss === 0 ? "" : `:${pad(ss)}`}`;
+}
+var formatWallDate = (f) => `${f.year}-${pad(f.month)}-${pad(f.day)}`;
+var formatWallDateTime = (f) => `${formatWallDate(f)}T${pad(f.hour)}:${pad(f.minute)}:${pad(f.second)}`;
+function assertValidDate(date) {
+  const ms = date.getTime();
+  if (Number.isNaN(ms)) throw new RangeError("Invalid time value");
+  return ms;
+}
+function toWireDateTime(date, options) {
+  const timeZone = options?.timeZone;
+  const withOffset = options?.offset === true;
+  if (timeZone === void 0) {
+    const wall2 = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+    if (!withOffset) return wall2;
+    assertValidDate(date);
+    return wall2 + formatOffset(-date.getTimezoneOffset());
+  }
+  const ms = assertValidDate(date);
+  const wall = formatWallDateTime(zonedFields(ms, timeZone));
+  return withOffset ? wall + formatOffset(offsetMinutes(ms, timeZone)) : wall;
+}
+function toWireDate(date, options) {
+  const timeZone = options?.timeZone;
+  if (timeZone === void 0) {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+  }
+  return formatWallDate(zonedFields(assertValidDate(date), timeZone));
+}
+var WALL_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d+))?$/;
+function parseWallText(text, original) {
+  const m = text.match(WALL_PATTERN);
+  if (!m) throw new Error(`\uC62C\uBC14\uB978 datetime \uD615\uC2DD\uC774 \uC544\uB2D9\uB2C8\uB2E4: ${original}`);
+  const [, y, mo, day, h, mi, s = "0", frac = "0"] = m;
+  return {
+    year: Number(y),
+    month: Number(mo),
+    day: Number(day),
+    hour: Number(h),
+    minute: Number(mi),
+    second: Number(s),
+    millisecond: Number((frac + "000").slice(0, 3))
+    // JS Date 는 ms 정밀도까지만
+  };
 }
-function toWireDate(date) {
-  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+function assertValidWall(f, original) {
+  const d = new Date(wallAsUtcMs(f));
+  if (d.getUTCFullYear() !== f.year || d.getUTCMonth() !== f.month - 1 || d.getUTCDate() !== f.day || d.getUTCHours() !== f.hour || d.getUTCMinutes() !== f.minute || d.getUTCSeconds() !== f.second) {
+    throw new Error(`\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 datetime \uAC12\uC785\uB2C8\uB2E4: ${original}`);
+  }
 }
-function parseWireDateTime(value) {
-  const stripped = stripZone(value.trim());
-  const m = stripped.match(
-    /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d+))?$/
-  );
-  if (!m) throw new Error(`\uC62C\uBC14\uB978 datetime \uD615\uC2DD\uC774 \uC544\uB2D9\uB2C8\uB2E4: ${value}`);
-  const [, y, mo, day, h, mi, s = "0", frac = "0"] = m;
-  const ms = Number((frac + "000").slice(0, 3));
-  const date = new Date(Number(y), Number(mo) - 1, Number(day), Number(h), Number(mi), Number(s), ms);
-  if (date.getFullYear() !== Number(y) || date.getMonth() !== Number(mo) - 1 || date.getDate() !== Number(day) || date.getHours() !== Number(h) || date.getMinutes() !== Number(mi) || date.getSeconds() !== Number(s)) {
+function matchRfc3339Offset(value) {
+  const tIndex = value.indexOf("T");
+  if (tIndex === -1) return null;
+  const m = value.slice(tIndex).match(/(?:[Zz]|([+-])(\d{2}):(\d{2}))$/);
+  if (!m || m.index === void 0) return null;
+  const [token, sign, hh, mm] = m;
+  const index = value.length - token.length;
+  if (sign === void 0) return { index, minutes: 0 };
+  const hours = Number(hh);
+  const minutes = Number(mm);
+  if (hours > 23 || minutes > 59) {
+    throw new Error(`\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 \uC624\uD504\uC14B\uC785\uB2C8\uB2E4: ${value}`);
+  }
+  return { index, minutes: (sign === "-" ? -1 : 1) * (hours * 60 + minutes) };
+}
+function parseWireDateTime(value, options) {
+  const timeZone = options?.timeZone;
+  const policy = options?.inboundOffset ?? "drop";
+  if (policy !== "drop" && policy !== "convert" && policy !== "reject") {
+    throw new RangeError(`\uC54C \uC218 \uC5C6\uB294 inboundOffset \uC815\uCC45\uC785\uB2C8\uB2E4: ${String(policy)}`);
+  }
+  if (timeZone !== void 0) zoneFormatter(timeZone);
+  const trimmed = value.trim();
+  let wallText = trimmed;
+  let offset;
+  if (policy === "drop") {
+    wallText = stripZone(trimmed);
+  } else {
+    const found = matchRfc3339Offset(trimmed);
+    if (found) {
+      if (policy === "reject") {
+        throw new RangeError(`\uC624\uD504\uC14B\uC774 \uBD99\uC740 datetime \uC740 \uD5C8\uC6A9\uB418\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4(inboundOffset: "reject"): ${value}`);
+      }
+      offset = found.minutes;
+      wallText = trimmed.slice(0, found.index);
+    }
+  }
+  const f = parseWallText(wallText, value);
+  if (offset !== void 0) {
+    assertValidWall(f, value);
+    return new Date(wallAsUtcMs(f) - offset * 6e4);
+  }
+  if (timeZone !== void 0) {
+    assertValidWall(f, value);
+    return new Date(wallToEpoch(f, timeZone));
+  }
+  const date = new Date(f.year, f.month - 1, f.day, f.hour, f.minute, f.second, f.millisecond);
+  if (date.getFullYear() !== f.year || date.getMonth() !== f.month - 1 || date.getDate() !== f.day || date.getHours() !== f.hour || date.getMinutes() !== f.minute || date.getSeconds() !== f.second) {
     throw new Error(`\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 datetime \uAC12\uC785\uB2C8\uB2E4: ${value}`);
   }
   return date;
@@ -1192,25 +1761,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 };
 }
@@ -1883,6 +2449,8 @@ function matchesHangul(query, target) {
   CircuitOpenError,
   DEFAULT_CSRF_COOKIE_NAME,
   DEFAULT_CSRF_HEADER_NAME,
+  FIXED_MESSAGE_KEYS,
+  MESSAGES,
   ResultCode,
   WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount,
@@ -1900,16 +2468,22 @@ 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,
@@ -1925,16 +2499,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,
@@ -1943,6 +2523,7 @@ function matchesHangul(query, target) {
   sniffFile,
   stripZone,
   toChosung,
+  toCommonResultCode,
   toE164,
   toFormalNotation,
   toKoreanWords,