@rscc/common-core 0.5.0 → 0.6.0

package/README.md

@@ -30,7 +30,7 @@ npm i @rscc/common-core
 | sseEvents | `createSseEventParser` · `parseSseEvents` · `readSseEvents` · `formatSseEvent` · `formatSseComment` · `SseEvent` · `SseEventParser` · `SseEventParserOptions` · `ReadSseEventsOptions` · `ReadSseEventsResult` · `FormatSseEventOptions` | 범용 SSE — WHATWG 표준 파서(`event`/`id`/`retry`, CRLF·CR, BOM)·스트림 리더(중단·`Last-Event-ID` 이어받기)·정규 빌더/하트비트 |
 | jwt | `decodeJwtPayload` · `getTokenExpiry` · `isTokenExpired` | base64url 디코드만 — **서명 미검증**, 만료 판단은 fail-closed |
 | masking | `maskSecret` · `maskName` · `maskPhone` · `maskEmail` · `maskCardNumber` | 시크릿(앞4+뒤4)·이름·휴대폰·이메일·카드번호 마스킹 |
-| datetime | `toWireDateTime` · `toWireDate` · `parseWireDateTime` · `stripZone` | 오프셋 없는 LocalDateTime 와이어 형식 — `toISOString()`(Z) 의 9시간 스큐 차단 |
+| datetime | `toWireDateTime` · `toWireDate` · `parseWireDateTime` · `stripZone` · `WireDateTimeFormatOptions` · `WireDateFormatOptions` · `WireDateTimeParseOptions` · `InboundOffsetPolicy` | 오프셋 없는 LocalDateTime 와이어 형식(기본) — `toISOString()`(Z) 의 9시간 스큐 차단. opt-in 기준 시간대(`timeZone`)·offset 프로필(`offset`)·수신 오프셋 정책(`inboundOffset`) |
 | chosung | `toChosung` · `isChosungQuery` | 한글 초성 변환·초성 질의 판별 (자동완성) |
 | retry | `retry` · `isRetryableStatus` · `parseRetryAfterMs` · `RetryOptions` | 지수 백오프 + full jitter, 시간 예산, `Retry-After` 파싱 |
 | cache | `createTtlCache` · `TtlCache<K,V>` · `TtlCacheOptions` | TTL 캐시 + single-flight(동일 키 로더 1회 공유), lazy expiry |
@@ -268,6 +268,49 @@ formatSseComment("ping"); // ": ping\n\n" — 하트비트(이벤트 없음)
 - 권장 응답 헤더: `Content-Type: text/event-stream`, `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no`.
 - React 에서는 `@rscc/common-react` 의 `useSseEvents`(재연결 시 `Last-Event-ID`·서버 `retry:` 존중)를 쓴다.
 
+### 날짜·시각 — 기준 시간대 · offset 프로필 (opt-in)
+
+**기본은 local 프로필** — 옵션을 주지 않으면 현행 그대로(실행 환경 로컬 게터, 오프셋 없는 `yyyy-MM-ddTHH:mm:ss`,
+수신 오프셋은 버림). 서비스 단위로 기준 시간대와 offset 프로필을 켤 수 있다.
+
+```ts
+import { toWireDateTime, toWireDate, parseWireDateTime } from "@rscc/common-core";
+
+const at = new Date("2026-07-10T04:00:00Z");
+toWireDateTime(at);                                              // 로컬 게터 (기본·현행)
+toWireDateTime(at, { timeZone: "Asia/Seoul" });                  // "2026-07-10T13:00:00"        (DT-01)
+toWireDateTime(at, { timeZone: "Asia/Seoul", offset: true });    // "2026-07-10T13:00:00+09:00"  (DT-02)
+toWireDateTime(at, { timeZone: "UTC", offset: true });           // "2026-07-10T04:00:00Z"       (DT-03 — 0 은 Z)
+toWireDateTime(at, { offset: true });                            // 호스트 오프셋(-getTimezoneOffset) 부착
+toWireDate(at, { timeZone: "Asia/Seoul" });                      // "2026-07-10"
+
+// 수신 — 오프셋 없는 벽시계를 기준 시간대로 해석 (DST 갭은 갭 길이만큼 뒤로, 겹침은 이른 오프셋)
+parseWireDateTime("2026-07-10T13:00:00", { timeZone: "Asia/Seoul" });          // 04:00Z   (DT-06)
+parseWireDateTime("2026-03-08T02:30:00", { timeZone: "America/New_York" });    // 07:30Z   (DT-12 갭)
+parseWireDateTime("2026-11-01T01:30:00", { timeZone: "America/New_York" });    // 05:30Z   (DT-13 겹침)
+
+// 수신 오프셋 정책 — 오프셋이 붙은 입력
+parseWireDateTime("2026-07-10T04:00:00Z", { inboundOffset: "convert" }); // 정확한 순간 04:00Z (timeZone 무관)
+parseWireDateTime("2026-07-10T04:00:00Z", { timeZone: "Asia/Seoul" });   // drop(기본) — 벽시계 04:00 KST (현행 스큐)
+parseWireDateTime("2026-07-10T04:00:00Z", { inboundOffset: "reject" });  // RangeError
+```
+
+| 옵션 | 함수 | 기본 | 설명 |
+|---|---|---|---|
+| `timeZone` | 세 함수 모두 | 실행 환경 로컬 | IANA 이름(`Asia/Seoul`·`UTC`·`America/New_York`). 잘못된 이름은 `Intl.DateTimeFormat` 의 `RangeError` |
+| `offset` | `toWireDateTime` | `false` | offset 프로필 — 그 순간의 기준 시간대 오프셋(`Z` / `±HH:MM`) 부착 |
+| `inboundOffset` | `parseWireDateTime` | `"drop"` | `drop` 오프셋 버리고 벽시계(현행) · `convert` 오프셋으로 정확한 순간 · `reject` `RangeError` |
+
+- **프로필 전환 순서**: offset 프로필로 바꾸는 것은 그 서비스 API 에 breaking 이다(현행 Jackson `LocalDateTime` 리더는
+  `+09:00` 을 거부). **클라이언트가 먼저 `inboundOffset: "convert"` 를 켜고 배포**한 뒤 서버가 offset 프로필로 바꾼다.
+  클라이언트 발신에 `offset: true` 를 켜는 것도 서버 전환 이후다.
+- `convert`·`reject` 는 RFC 3339 오프셋(`Z`·`±HH:MM`)만 인식한다 — `+0900` 같은 표기는 형식 오류(`drop` 은 현행대로 버림).
+  오프셋 없는 입력은 모든 정책에서 벽시계 그대로.
+- 발신은 초 단위(밀리초 절단 — 현행), 수신 소수부는 밀리초까지 보존(`.123456789` → `.123`, DT-14).
+- 시간대 계산은 `Intl.DateTimeFormat(...).formatToParts` 만 쓴다(의존성 0, 시간대별 포매터 캐시) — Intl 의 IANA 시간대
+  지원이 필요하다(Node 20+ 공식 빌드(full-ICU)·모던 브라우저는 기본 포함).
+- 골든 벡터 DT-01~14(contracts/datetime.md)는 `timeZone` 을 명시해 실행 머신의 시간대와 무관하게 검증한다.
+
 ### 메시지 다국어 — 내장 ko(기본)·en
 
 라이브러리가 내보내는 와이어 메시지(서버 봉투 메시지 22키 + 클라이언트 로컬 메시지 3키)를 **ko·en 으로 내장**한다.
@@ -350,6 +393,8 @@ const dec = decryptAesGcm(enc, key);      // 키 상이·변조 시 CryptoError
 - `isValidRrn` 은 체크섬을 포함하지 않는다(2020-10 이후 발급분은 체크섬 불성립) — `rrnChecksumOkLegacy` 는 레거시 정합 검사 전용.
 - `signWebhook`/`verifyWebhook` 은 WebCrypto 기반이라 **async** 다 (Java/Python 은 동기).
 - 서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시는 **인스턴스(프로세스) 로컬** 상태다 — 분산 공유되지 않는다.
+- datetime 의 `timeZone` 옵션은 `Intl.DateTimeFormat` 의 IANA 시간대 지원에 의존한다 — 지원하지 않는 런타임(시간대 데이터가
+  없는 경량 JS 엔진 등)에서는 `RangeError`. 옵션을 주지 않은 기본 경로는 `Intl` 을 쓰지 않는다.
 - 내장 메시지 언어는 `ko`·`en` 뿐이다 — 그 외 언어는 `getMessage` 의 `overrides`(업로드는 `messages`)로 공급할 것.
 - `@rscc/common-core/crypto` 는 `node:crypto` 를 쓰는 **Node 전용** 서브패스 — 브라우저 번들에 포함하지 말 것.
 - 서브패스는 `exports` 맵으로만 노출된다 — TypeScript `moduleResolution` 이 레거시 `node`(`node10`)면

package/dist/index.cjs

@@ -1021,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;

package/dist/index.d.cts

@@ -823,30 +823,93 @@ declare function maskEmail(email: string): string;
 declare function maskCardNumber(cardNumber: string): string;
 
 /**
- * 오프셋 없는 LocalDateTime 와이어 직렬화 헬퍼 — contracts/datetime.md.
+ * LocalDateTime 와이어 직렬화 헬퍼 — contracts/datetime.md.
  *
- * 핵심 규약: **와이어에는 시간대/오프셋을 절대 싣지 않는다.** 값은 서버 기준
- * (운영 전제: KST) 벽시계 시각으로 해석된다.
+ * 두 프로필:
+ * - **local 프로필(기본·현행)** — 와이어에 시간대/오프셋을 싣지 않는다(`yyyy-MM-ddTHH:mm:ss`).
+ *   값은 서버 기준(운영 전제: KST) 벽시계 시각으로 해석된다. 옵션을 주지 않으면 항상 이 동작이다.
+ * - **offset 프로필(opt-in)** — `yyyy-MM-ddTHH:mm:ss(Z|±HH:MM)`. 오프셋은 그 순간의 기준 시간대
+ *   오프셋이며 0 오프셋은 `Z`. `toWireDateTime(date, { offset: true })` 로 켠다.
+ *
+ * 기준 시간대(wire zone)는 기본이 **실행 환경의 로컬 시간대**(브라우저/Node 로컬 게터 — 현행)이고,
+ * `timeZone`(IANA 이름: `Asia/Seoul`, `UTC`, `America/New_York`)으로 고정할 수 있다. 시간대 계산은
+ * `Intl.DateTimeFormat(...).formatToParts` 만 쓴다(런타임 의존성 0 — Node full-ICU / 모던 브라우저 전제).
+ * 잘못된 `timeZone` 은 `Intl.DateTimeFormat` 이 던지는 `RangeError` 를 그대로 전파한다.
  *
  * ⚠️ Z 스큐 경고(datetime.md): `new Date(x).toISOString()` 은 UTC 로 변환해 끝에
  * `Z` 를 붙인다. 서버(`LocalDateTime`)는 그 `Z` 를 조용히 버리고 나머지를 KST 벽시계로
- * 재해석해 **9시간 스큐**를 만든다. 이 모듈의 직렬화 함수는 오프셋을 절대 만들지 않아
+ * 재해석해 **9시간 스큐**를 만든다. 이 모듈의 직렬화 함수는 기본적으로 오프셋을 만들지 않아
  * 그 경로를 원천 차단한다. `<input type="datetime-local">` 값은 이미 오프셋 없는
  * 형식이므로 그대로 보내면 되고, Date 객체를 보내야 할 땐 {@link toWireDateTime} 을 쓴다.
+ * offset 프로필(`offset: true`)은 **서버가 offset 프로필로 전환한 서비스에서만** 쓸 것.
  */
+/** {@link toWireDateTime} 옵션 — 모두 opt-in, 생략 시 현행(로컬 게터·오프셋 없음). */
+interface WireDateTimeFormatOptions {
+    /**
+     * 기준 시간대(IANA 이름, 예: `"Asia/Seoul"`, `"UTC"`). 지정하면 그 순간을 이 시간대의 벽시계로 직렬화한다.
+     * 생략 시 실행 환경의 로컬 시간대(현행). 잘못된 이름은 `RangeError`.
+     */
+    timeZone?: string;
+    /**
+     * `true` 면 offset 프로필 — 그 순간의 기준 시간대 오프셋을 붙인다(0 은 `Z`, 그 외 `±HH:MM`).
+     * `timeZone` 없이 켜면 호스트 오프셋(`-date.getTimezoneOffset()`)을 쓴다. 기본 `false`(현행).
+     */
+    offset?: boolean;
+}
+/** {@link toWireDate} 옵션 — 생략 시 현행(로컬 날짜). */
+interface WireDateFormatOptions {
+    /** 기준 시간대(IANA 이름). 지정하면 그 순간의 이 시간대 날짜를 직렬화한다. 잘못된 이름은 `RangeError`. */
+    timeZone?: string;
+}
 /**
- * Date 의 **로컬** 필드를 `yyyy-MM-ddTHH:mm:ss`(오프셋 없음)로 직렬화한다.
- * `toISOString()`(UTC/Z) 대신 이 함수를 쓸 것 — 그래야 스큐가 생기지 않는다.
+ * 수신 오프셋 정책 — 오프셋이 붙은 문자열을 받았을 때의 동작(contracts/datetime.md §수신 오프셋 정책).
+ * - `"drop"`(기본·현행): 오프셋(`Z`·`±HH:MM`·`±HHMM`)을 버리고 나머지를 벽시계로 해석 — Z 스큐 그대로.
+ * - `"convert"`: 오프셋으로 정확한 순간을 계산(`timeZone` 무관). RFC 3339 오프셋(`Z`·`±HH:MM`)만 인식.
+ * - `"reject"`: RFC 3339 오프셋이 붙어 있으면 `RangeError`.
  */
-declare function toWireDateTime(date: Date): string;
-/** Date 의 로컬 날짜를 `yyyy-MM-dd` 로 직렬화한다. */
-declare function toWireDate(date: Date): string;
+type InboundOffsetPolicy = "drop" | "convert" | "reject";
+/** {@link parseWireDateTime} 옵션 — 모두 opt-in, 생략 시 현행(로컬 해석·오프셋 drop). */
+interface WireDateTimeParseOptions {
+    /**
+     * 기준 시간대(IANA 이름). 오프셋 없는 벽시계를 이 시간대 기준으로 해석한다(DST 갭은 갭 길이만큼 뒤로,
+     * 겹침은 이른 오프셋). 생략 시 실행 환경의 로컬 시간대(현행). 잘못된 이름은 `RangeError`.
+     */
+    timeZone?: string;
+    /** 수신 오프셋 정책. 기본 `"drop"`(현행). */
+    inboundOffset?: InboundOffsetPolicy;
+}
 /**
- * 와이어 datetime 문자열(`yyyy-MM-ddTHH:mm[:ss[.fff]]`)을 **로컬 시간대**로 해석한
- * Date 로 파싱한다(사용자·서버가 모두 KST 라는 전제). 끝의 `Z`/오프셋은 무시하고
- * 벽시계 숫자만 취한다(Java Jackson lenient 파리티). 형식 불일치 시 throw.
+ * Date 를 와이어 datetime(초 단위)으로 직렬화한다. `toISOString()`(UTC/Z) 대신 이 함수를 쓸 것.
+ *
+ * - 옵션 없음(기본·현행): **로컬** 필드를 `yyyy-MM-ddTHH:mm:ss`(오프셋 없음)로 — 스큐가 생기지 않는다.
+ * - `timeZone`: 그 순간을 해당 IANA 시간대의 벽시계로 직렬화.
+ * - `offset: true`: offset 프로필 — 그 순간의 기준 시간대 오프셋을 붙인다(`Z` / `±HH:MM`).
+ *   `timeZone` 이 없으면 호스트 오프셋(`-date.getTimezoneOffset()`).
+ *
+ * @throws RangeError 잘못된 `timeZone`, 또는 시간대/오프셋 옵션과 함께 준 잘못된 Date(Invalid Date)
+ */
+declare function toWireDateTime(date: Date, options?: WireDateTimeFormatOptions): string;
+/**
+ * Date 의 날짜를 `yyyy-MM-dd` 로 직렬화한다. 기본은 로컬 날짜(현행), `timeZone` 을 주면 그 순간의
+ * 해당 시간대 날짜.
+ *
+ * @throws RangeError 잘못된 `timeZone`, 또는 `timeZone` 과 함께 준 잘못된 Date
+ */
+declare function toWireDate(date: Date, options?: WireDateFormatOptions): string;
+/**
+ * 와이어 datetime 문자열(`yyyy-MM-ddTHH:mm[:ss[.fff…]]`, 소수부는 밀리초까지 보존)을 Date 로 파싱한다.
+ *
+ * - 옵션 없음(기본·현행): **로컬 시간대**로 해석(사용자·서버가 모두 KST 라는 전제). 끝의 `Z`/오프셋은
+ *   무시하고 벽시계 숫자만 취한다(Java Jackson lenient 파리티). 로컬 DST 갭 시각은 throw(현행).
+ * - `timeZone`: 오프셋 없는 벽시계를 그 IANA 시간대로 해석한다 — DST 갭은 갭 길이만큼 뒤로, 겹침은 이른 오프셋.
+ * - `inboundOffset`: 오프셋이 붙은 입력의 정책 — `"drop"`(기본·현행) / `"convert"`(오프셋으로 정확한 순간,
+ *   `timeZone` 무관) / `"reject"`(`RangeError`). `convert`·`reject` 는 RFC 3339 오프셋(`Z`·`±HH:MM`)만
+ *   인식하므로 `+0900` 같은 다른 표기는 형식 오류가 된다. 오프셋 없는 입력은 모든 정책에서 벽시계 그대로.
+ *
+ * @throws Error 형식 불일치·범위를 벗어난 값(25시·2월 30일 등)·잘못된 오프셋
+ * @throws RangeError 잘못된 `timeZone`·알 수 없는 `inboundOffset`, `"reject"` 정책에서 오프셋이 붙은 입력
  */
-declare function parseWireDateTime(value: string): Date;
+declare function parseWireDateTime(value: string, options?: WireDateTimeParseOptions): Date;
 /**
  * 문자열 끝의 `Z` 또는 `±HH:MM`/`±HHMM` 오프셋을 제거한다(발신 전 sanitize).
  * 시각 자체는 변환하지 않고 벽시계 부분만 남긴다. 오프셋이 없으면 원본을 그대로 반환.
@@ -1792,4 +1855,4 @@ declare function composeHangul(s: string): string;
  */
 declare function matchesHangul(query: string, target: string): boolean;
 
-export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BuiltinLanguage, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type CsrfOptions, DEFAULT_CSRF_COOKIE_NAME, DEFAULT_CSRF_HEADER_NAME, type ErrorCodeValue, FIXED_MESSAGE_KEYS, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type FormatSseEventOptions, type GetMessageOptions, type JosaPair, type ListQueryOptions, MESSAGES, type MessageKey, type MessageOverrides, type PageResponse, type PhoneType, type ReadSseEventsOptions, type ReadSseEventsResult, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseEvent, type SseEventParser, type SseEventParserOptions, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadMessageKey, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, 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, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, negotiateLanguage, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseChatPayload, parseFlag, parseRetryAfterMs, parseSseEvents, parseSseFrame, parseWireDateTime, pickJosa, readCookie, readSseChatEvents, readSseEvents, readSseStream, resultCodeForStatus, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toCommonResultCode, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BuiltinLanguage, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type CsrfOptions, DEFAULT_CSRF_COOKIE_NAME, DEFAULT_CSRF_HEADER_NAME, type ErrorCodeValue, FIXED_MESSAGE_KEYS, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type FormatSseEventOptions, type GetMessageOptions, type InboundOffsetPolicy, type JosaPair, type ListQueryOptions, MESSAGES, type MessageKey, type MessageOverrides, type PageResponse, type PhoneType, type ReadSseEventsOptions, type ReadSseEventsResult, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseEvent, type SseEventParser, type SseEventParserOptions, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadMessageKey, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, type WireDateFormatOptions, type WireDateTimeFormatOptions, type WireDateTimeParseOptions, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, 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, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, negotiateLanguage, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseChatPayload, parseFlag, parseRetryAfterMs, parseSseEvents, parseSseFrame, parseWireDateTime, pickJosa, readCookie, readSseChatEvents, readSseEvents, readSseStream, resultCodeForStatus, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toCommonResultCode, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };

package/dist/index.d.ts

@@ -823,30 +823,93 @@ declare function maskEmail(email: string): string;
 declare function maskCardNumber(cardNumber: string): string;
 
 /**
- * 오프셋 없는 LocalDateTime 와이어 직렬화 헬퍼 — contracts/datetime.md.
+ * LocalDateTime 와이어 직렬화 헬퍼 — contracts/datetime.md.
  *
- * 핵심 규약: **와이어에는 시간대/오프셋을 절대 싣지 않는다.** 값은 서버 기준
- * (운영 전제: KST) 벽시계 시각으로 해석된다.
+ * 두 프로필:
+ * - **local 프로필(기본·현행)** — 와이어에 시간대/오프셋을 싣지 않는다(`yyyy-MM-ddTHH:mm:ss`).
+ *   값은 서버 기준(운영 전제: KST) 벽시계 시각으로 해석된다. 옵션을 주지 않으면 항상 이 동작이다.
+ * - **offset 프로필(opt-in)** — `yyyy-MM-ddTHH:mm:ss(Z|±HH:MM)`. 오프셋은 그 순간의 기준 시간대
+ *   오프셋이며 0 오프셋은 `Z`. `toWireDateTime(date, { offset: true })` 로 켠다.
+ *
+ * 기준 시간대(wire zone)는 기본이 **실행 환경의 로컬 시간대**(브라우저/Node 로컬 게터 — 현행)이고,
+ * `timeZone`(IANA 이름: `Asia/Seoul`, `UTC`, `America/New_York`)으로 고정할 수 있다. 시간대 계산은
+ * `Intl.DateTimeFormat(...).formatToParts` 만 쓴다(런타임 의존성 0 — Node full-ICU / 모던 브라우저 전제).
+ * 잘못된 `timeZone` 은 `Intl.DateTimeFormat` 이 던지는 `RangeError` 를 그대로 전파한다.
  *
  * ⚠️ Z 스큐 경고(datetime.md): `new Date(x).toISOString()` 은 UTC 로 변환해 끝에
  * `Z` 를 붙인다. 서버(`LocalDateTime`)는 그 `Z` 를 조용히 버리고 나머지를 KST 벽시계로
- * 재해석해 **9시간 스큐**를 만든다. 이 모듈의 직렬화 함수는 오프셋을 절대 만들지 않아
+ * 재해석해 **9시간 스큐**를 만든다. 이 모듈의 직렬화 함수는 기본적으로 오프셋을 만들지 않아
  * 그 경로를 원천 차단한다. `<input type="datetime-local">` 값은 이미 오프셋 없는
  * 형식이므로 그대로 보내면 되고, Date 객체를 보내야 할 땐 {@link toWireDateTime} 을 쓴다.
+ * offset 프로필(`offset: true`)은 **서버가 offset 프로필로 전환한 서비스에서만** 쓸 것.
  */
+/** {@link toWireDateTime} 옵션 — 모두 opt-in, 생략 시 현행(로컬 게터·오프셋 없음). */
+interface WireDateTimeFormatOptions {
+    /**
+     * 기준 시간대(IANA 이름, 예: `"Asia/Seoul"`, `"UTC"`). 지정하면 그 순간을 이 시간대의 벽시계로 직렬화한다.
+     * 생략 시 실행 환경의 로컬 시간대(현행). 잘못된 이름은 `RangeError`.
+     */
+    timeZone?: string;
+    /**
+     * `true` 면 offset 프로필 — 그 순간의 기준 시간대 오프셋을 붙인다(0 은 `Z`, 그 외 `±HH:MM`).
+     * `timeZone` 없이 켜면 호스트 오프셋(`-date.getTimezoneOffset()`)을 쓴다. 기본 `false`(현행).
+     */
+    offset?: boolean;
+}
+/** {@link toWireDate} 옵션 — 생략 시 현행(로컬 날짜). */
+interface WireDateFormatOptions {
+    /** 기준 시간대(IANA 이름). 지정하면 그 순간의 이 시간대 날짜를 직렬화한다. 잘못된 이름은 `RangeError`. */
+    timeZone?: string;
+}
 /**
- * Date 의 **로컬** 필드를 `yyyy-MM-ddTHH:mm:ss`(오프셋 없음)로 직렬화한다.
- * `toISOString()`(UTC/Z) 대신 이 함수를 쓸 것 — 그래야 스큐가 생기지 않는다.
+ * 수신 오프셋 정책 — 오프셋이 붙은 문자열을 받았을 때의 동작(contracts/datetime.md §수신 오프셋 정책).
+ * - `"drop"`(기본·현행): 오프셋(`Z`·`±HH:MM`·`±HHMM`)을 버리고 나머지를 벽시계로 해석 — Z 스큐 그대로.
+ * - `"convert"`: 오프셋으로 정확한 순간을 계산(`timeZone` 무관). RFC 3339 오프셋(`Z`·`±HH:MM`)만 인식.
+ * - `"reject"`: RFC 3339 오프셋이 붙어 있으면 `RangeError`.
  */
-declare function toWireDateTime(date: Date): string;
-/** Date 의 로컬 날짜를 `yyyy-MM-dd` 로 직렬화한다. */
-declare function toWireDate(date: Date): string;
+type InboundOffsetPolicy = "drop" | "convert" | "reject";
+/** {@link parseWireDateTime} 옵션 — 모두 opt-in, 생략 시 현행(로컬 해석·오프셋 drop). */
+interface WireDateTimeParseOptions {
+    /**
+     * 기준 시간대(IANA 이름). 오프셋 없는 벽시계를 이 시간대 기준으로 해석한다(DST 갭은 갭 길이만큼 뒤로,
+     * 겹침은 이른 오프셋). 생략 시 실행 환경의 로컬 시간대(현행). 잘못된 이름은 `RangeError`.
+     */
+    timeZone?: string;
+    /** 수신 오프셋 정책. 기본 `"drop"`(현행). */
+    inboundOffset?: InboundOffsetPolicy;
+}
 /**
- * 와이어 datetime 문자열(`yyyy-MM-ddTHH:mm[:ss[.fff]]`)을 **로컬 시간대**로 해석한
- * Date 로 파싱한다(사용자·서버가 모두 KST 라는 전제). 끝의 `Z`/오프셋은 무시하고
- * 벽시계 숫자만 취한다(Java Jackson lenient 파리티). 형식 불일치 시 throw.
+ * Date 를 와이어 datetime(초 단위)으로 직렬화한다. `toISOString()`(UTC/Z) 대신 이 함수를 쓸 것.
+ *
+ * - 옵션 없음(기본·현행): **로컬** 필드를 `yyyy-MM-ddTHH:mm:ss`(오프셋 없음)로 — 스큐가 생기지 않는다.
+ * - `timeZone`: 그 순간을 해당 IANA 시간대의 벽시계로 직렬화.
+ * - `offset: true`: offset 프로필 — 그 순간의 기준 시간대 오프셋을 붙인다(`Z` / `±HH:MM`).
+ *   `timeZone` 이 없으면 호스트 오프셋(`-date.getTimezoneOffset()`).
+ *
+ * @throws RangeError 잘못된 `timeZone`, 또는 시간대/오프셋 옵션과 함께 준 잘못된 Date(Invalid Date)
+ */
+declare function toWireDateTime(date: Date, options?: WireDateTimeFormatOptions): string;
+/**
+ * Date 의 날짜를 `yyyy-MM-dd` 로 직렬화한다. 기본은 로컬 날짜(현행), `timeZone` 을 주면 그 순간의
+ * 해당 시간대 날짜.
+ *
+ * @throws RangeError 잘못된 `timeZone`, 또는 `timeZone` 과 함께 준 잘못된 Date
+ */
+declare function toWireDate(date: Date, options?: WireDateFormatOptions): string;
+/**
+ * 와이어 datetime 문자열(`yyyy-MM-ddTHH:mm[:ss[.fff…]]`, 소수부는 밀리초까지 보존)을 Date 로 파싱한다.
+ *
+ * - 옵션 없음(기본·현행): **로컬 시간대**로 해석(사용자·서버가 모두 KST 라는 전제). 끝의 `Z`/오프셋은
+ *   무시하고 벽시계 숫자만 취한다(Java Jackson lenient 파리티). 로컬 DST 갭 시각은 throw(현행).
+ * - `timeZone`: 오프셋 없는 벽시계를 그 IANA 시간대로 해석한다 — DST 갭은 갭 길이만큼 뒤로, 겹침은 이른 오프셋.
+ * - `inboundOffset`: 오프셋이 붙은 입력의 정책 — `"drop"`(기본·현행) / `"convert"`(오프셋으로 정확한 순간,
+ *   `timeZone` 무관) / `"reject"`(`RangeError`). `convert`·`reject` 는 RFC 3339 오프셋(`Z`·`±HH:MM`)만
+ *   인식하므로 `+0900` 같은 다른 표기는 형식 오류가 된다. 오프셋 없는 입력은 모든 정책에서 벽시계 그대로.
+ *
+ * @throws Error 형식 불일치·범위를 벗어난 값(25시·2월 30일 등)·잘못된 오프셋
+ * @throws RangeError 잘못된 `timeZone`·알 수 없는 `inboundOffset`, `"reject"` 정책에서 오프셋이 붙은 입력
  */
-declare function parseWireDateTime(value: string): Date;
+declare function parseWireDateTime(value: string, options?: WireDateTimeParseOptions): Date;
 /**
  * 문자열 끝의 `Z` 또는 `±HH:MM`/`±HHMM` 오프셋을 제거한다(발신 전 sanitize).
  * 시각 자체는 변환하지 않고 벽시계 부분만 남긴다. 오프셋이 없으면 원본을 그대로 반환.
@@ -1792,4 +1855,4 @@ declare function composeHangul(s: string): string;
  */
 declare function matchesHangul(query: string, target: string): boolean;
 
-export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BuiltinLanguage, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type CsrfOptions, DEFAULT_CSRF_COOKIE_NAME, DEFAULT_CSRF_HEADER_NAME, type ErrorCodeValue, FIXED_MESSAGE_KEYS, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type FormatSseEventOptions, type GetMessageOptions, type JosaPair, type ListQueryOptions, MESSAGES, type MessageKey, type MessageOverrides, type PageResponse, type PhoneType, type ReadSseEventsOptions, type ReadSseEventsResult, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseEvent, type SseEventParser, type SseEventParserOptions, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadMessageKey, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, 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, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, negotiateLanguage, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseChatPayload, parseFlag, parseRetryAfterMs, parseSseEvents, parseSseFrame, parseWireDateTime, pickJosa, readCookie, readSseChatEvents, readSseEvents, readSseStream, resultCodeForStatus, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toCommonResultCode, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BuiltinLanguage, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type CsrfOptions, DEFAULT_CSRF_COOKIE_NAME, DEFAULT_CSRF_HEADER_NAME, type ErrorCodeValue, FIXED_MESSAGE_KEYS, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type FormatSseEventOptions, type GetMessageOptions, type InboundOffsetPolicy, type JosaPair, type ListQueryOptions, MESSAGES, type MessageKey, type MessageOverrides, type PageResponse, type PhoneType, type ReadSseEventsOptions, type ReadSseEventsResult, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseEvent, type SseEventParser, type SseEventParserOptions, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadMessageKey, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, type WireDateFormatOptions, type WireDateTimeFormatOptions, type WireDateTimeParseOptions, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, 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, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, negotiateLanguage, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseChatPayload, parseFlag, parseRetryAfterMs, parseSseEvents, parseSseFrame, parseWireDateTime, pickJosa, readCookie, readSseChatEvents, readSseEvents, readSseStream, resultCodeForStatus, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toCommonResultCode, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };

package/dist/index.js

@@ -909,22 +909,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rscc/common-core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "RSCC 공통 코어 — CommonResponse 타입·apiClient(traceId·재시도·멱등성 키), SSE 파서, 회복탄력성(retry·서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시), 보안(마스킹·로그 리댁션·웹훅 서명·JWT 디코드·AES-GCM 서브패스), 와이어 계약 헬퍼, 한국 도메인 유틸. 프레임워크 무관, 런타임 의존성 0.",
   "keywords": [
     "rscc",