@remember-web/sse 0.1.0-alpha.1

package/src/core/eventNames.ts

@@ -0,0 +1,53 @@
+// 서버가 /v1/events 스트림으로 보내는 연결 수명주기 이벤트 — 도메인 이벤트와 달리 SDK가 소비합니다
+export const SERVER_CONNECTION_EVENTS = {
+  hello: 'hello',
+  goaway: 'goaway',
+} as const;
+
+/**
+ * @description SDK가 스스로 발화하는 이벤트 — 재수립(resync)·멈춘 사유(fatal)·미연결 지속(stalled)을 SDK가 알아채 알립니다
+ */
+export const SDK_EVENTS = {
+  resync: 'resync',
+  fatal: 'fatal',
+  stalled: 'stalled',
+} as const;
+
+/**
+ * @description 소비처로 배달하는 이름들 — 출처(서버·SDK)와 무관하게 "소비처가 보는가"만 봅니다.
+ * 워커는 구독 장부와 별개로 이 목록을 중계해야 합니다: 장부만 보고 붙이면 소비처에 영영 도달하지 않습니다.
+ * SDK 이벤트는 배달이 곧 존재 이유라 전부 파생합니다 — 나열하면 이름을 늘릴 때 빠뜨릴 자리가 생깁니다.
+ * 서버 연결 이벤트는 SDK가 소비하는 게 기본이라 배달할 것만 골라 넣습니다:
+ * goaway는 SDK가 action으로 재연결을 판단하고, 소비처는 reason으로 안내를 정합니다.
+ */
+export const FORWARDED_EVENTS = [
+  ...Object.values(SDK_EVENTS),
+  SERVER_CONNECTION_EVENTS.goaway,
+] as const;
+
+// 멤버십 검사는 Set 파생으로 — Object.hasOwn(Safari 15.4+)이 배포 하한을 만들지 않게 합니다
+const SERVER_CONNECTION_EVENT_NAMES: ReadonlySet<string> = new Set(
+  Object.values(SERVER_CONNECTION_EVENTS)
+);
+
+const FORWARDED_EVENT_NAMES: ReadonlySet<string> = new Set(FORWARDED_EVENTS);
+
+const isServerConnectionEvent = (type: string): boolean =>
+  SERVER_CONNECTION_EVENT_NAMES.has(type);
+
+const isForwardedEvent = (type: string): boolean =>
+  FORWARDED_EVENT_NAMES.has(type);
+
+/**
+ * @description 서버 스트림에 구독을 걸 이름인지 판정합니다 — 연결 이벤트와 중계 목록은 SDK가 소유합니다.
+ * 목록에서 판정을 파생해야 이름을 추가할 때 구독 제외가 따라옵니다: 빠지면 워커가 같은 이벤트를 두 번 배달합니다.
+ */
+export const isSubscribableEvent = (type: string): boolean =>
+  !isServerConnectionEvent(type) && !isForwardedEvent(type);
+
+/**
+ * @description 구독해도 배달되지 않는 이름인지 판정합니다 — 조용한 무배달 구독을 경고로 알리는 데 씁니다.
+ * 중계 목록에 있으면 SDK가 소비하더라도 소비처에 배달되므로 경고 대상이 아닙니다.
+ */
+export const isUndeliverableEvent = (type: string): boolean =>
+  isServerConnectionEvent(type) && !isForwardedEvent(type);

package/src/core/retryWait.ts

@@ -0,0 +1,18 @@
+/**
+ * @description 재시도 대기 Promise — 타이머 만료·abort 중 먼저 발생하는 쪽에서 resolve됩니다.
+ * 어느 경로로 풀리든 타이머와 abort 리스너를 함께 정리합니다.
+ */
+export const waitForRetry = (
+  delayMs: number,
+  signal: AbortSignal
+): Promise<void> =>
+  new Promise((resolve) => {
+    const finish = () => {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', finish);
+      resolve();
+    };
+
+    const timer = setTimeout(finish, delayMs);
+    signal.addEventListener('abort', finish);
+  });

package/src/core/statusMachine.ts

@@ -0,0 +1,56 @@
+import type { SseStatus } from './types';
+
+export type TransitionEvent =
+  | 'connect'
+  | 'hello'
+  | 'retryableFailure'
+  | 'fatalFailure'
+  | 'readyToRetry'
+  | 'disconnect';
+
+/**
+ * @description 상태 전이 규칙을 명시합니다
+ */
+const TRANSITIONS = {
+  idle: { connect: 'connecting', disconnect: 'closed' },
+  connecting: {
+    hello: 'open',
+    retryableFailure: 'reconnecting',
+    fatalFailure: 'fatal',
+    disconnect: 'closed',
+  },
+  open: {
+    retryableFailure: 'reconnecting',
+    fatalFailure: 'fatal',
+    disconnect: 'closed',
+  },
+  reconnecting: { readyToRetry: 'connecting', disconnect: 'closed' },
+  // closed 후 재연결을 열어둔 이유: React StrictMode 재마운트가 같은 인스턴스로 connect→disconnect→connect를 수행합니다
+  closed: { connect: 'connecting' },
+  fatal: { disconnect: 'closed' },
+} satisfies Record<SseStatus, Partial<Record<TransitionEvent, SseStatus>>>;
+
+/** @description 연결 상태머신 — 표에 선언된 전이만 수행하고, 전이가 일어날 때 onChange를 호출합니다 */
+export const createStatusMachine = (onChange: (status: SseStatus) => void) => {
+  let status: SseStatus = 'idle';
+
+  return {
+    get status(): SseStatus {
+      return status;
+    },
+    transition: (event: TransitionEvent): boolean => {
+      const transitions: Partial<Record<TransitionEvent, SseStatus>> =
+        TRANSITIONS[status];
+      const next = transitions[event];
+      if (next === undefined) {
+        return false;
+      }
+
+      status = next;
+      onChange(next);
+      return true;
+    },
+  };
+};
+
+export type StatusMachine = ReturnType<typeof createStatusMachine>;

package/src/core/stream.ts

@@ -0,0 +1,141 @@
+import { isSubscribableEvent, SERVER_CONNECTION_EVENTS } from './eventNames';
+import type { GoawayPayload } from './types';
+import { isGoawayAction, isGoawayReason } from './types';
+
+/**
+ * @description 스트림이 끊긴 이유.
+ * goaway는 서버가 예고하고 닫는 정상 종료라 백오프 없이 즉시 재수립하고,
+ * goaway-close는 서버가 재연결하지 말라고 한 것이라 루프를 끝냅니다.
+ */
+export type StreamOutcome = 'error' | 'goaway' | 'goaway-close';
+
+/**
+ * @description 끊김의 전말 — goaway 계열에만 페이로드가 붙습니다.
+ * 유니온으로 묶어 "outcome이 goaway일 때만 payload가 있다"를 타입이 강제하게 합니다.
+ */
+export type StreamClosure =
+  | { outcome: 'error' }
+  | { outcome: 'goaway' | 'goaway-close'; goaway: GoawayPayload };
+
+/**
+ * @description 한 EventSource에 리스너를 이미 건 이벤트 이름들 — 중복 부착을 막는 장부입니다.
+ * 소스가 바뀌면 리스너도 함께 사라지므로, 이 장부는 소스와 수명을 같이해야 합니다.
+ */
+export type AttachedEvents = Set<string>;
+
+const parsePayload = (event: { data?: unknown }): unknown => {
+  if (typeof event.data !== 'string' || event.data === '') {
+    return undefined;
+  }
+  try {
+    return JSON.parse(event.data);
+  } catch {
+    return event.data;
+  }
+};
+
+// 구버전 서버·잘린 프레임에서는 필드가 없거나 미지 값이 옵니다 — 아는 값만 남기고 나머지는 버립니다
+const toGoawayPayload = (parsed: unknown): GoawayPayload => {
+  if (typeof parsed !== 'object' || parsed === null) {
+    return {};
+  }
+
+  const { reason, action } = parsed as { reason?: unknown; action?: unknown };
+
+  return {
+    ...(isGoawayReason(reason) && { reason }),
+    ...(isGoawayAction(action) && { action }),
+  };
+};
+
+/**
+ * @description 도메인 이벤트 리스너를 소스에 1회 부착합니다 — SDK 예약 이벤트는 소비처로 흘리지 않습니다
+ */
+export const attachDomainListener = (
+  source: EventSource,
+  attachedEvents: AttachedEvents,
+  type: string,
+  deliver: (type: string, payload: unknown) => void
+): void => {
+  if (attachedEvents.has(type)) {
+    return;
+  }
+  if (!isSubscribableEvent(type)) {
+    return;
+  }
+
+  attachedEvents.add(type);
+  source.addEventListener(type, (event) => {
+    deliver(type, parsePayload(event));
+  });
+};
+
+export interface StreamHooks {
+  helloTimeoutMs: number;
+  /** @description hello 프레임 수신 — 수립으로 인정하면 true를 반환해 타임아웃을 해제시킵니다 */
+  onHello: () => boolean;
+  /**
+   * @description 끊김 확정 — resolve 전에 동기로 호출됩니다 (정리·상태 전이는 호출자 몫).
+   * goaway면 페이로드가 함께 옵니다: 소비처가 reason으로 안내를 정하도록 그대로 넘깁니다.
+   */
+  onClosed: (closure: StreamClosure) => void;
+}
+
+/**
+ * @description 콜백 세계(EventSource 이벤트·타이머·abort)를 Promise 하나로 바꾸는 경계 어댑터.
+ * 아래 결말 4개 중 먼저 발생하는 것으로 정확히 한 번 끝나고, hello는 결말이 아니라 수립 신호입니다.
+ */
+export const streamUntilClosed = (
+  source: EventSource,
+  signal: AbortSignal,
+  hooks: StreamHooks
+): Promise<StreamOutcome> =>
+  new Promise((resolve) => {
+    let settled = false;
+
+    const settle = (
+      closure: StreamClosure,
+      options: { notifyClosed: boolean }
+    ) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(helloTimer);
+      signal.removeEventListener('abort', onAbort);
+      if (options.notifyClosed) {
+        hooks.onClosed(closure);
+      }
+      resolve(closure.outcome);
+    };
+
+    const helloTimer = setTimeout(
+      () => settle({ outcome: 'error' }, { notifyClosed: true }),
+      hooks.helloTimeoutMs
+    );
+
+    source.addEventListener(SERVER_CONNECTION_EVENTS.goaway, (event) => {
+      const goaway = toGoawayPayload(parsePayload(event));
+      settle(
+        {
+          outcome: goaway.action === 'close' ? 'goaway-close' : 'goaway',
+          goaway,
+        },
+        { notifyClosed: true }
+      );
+    });
+
+    source.onerror = () => settle({ outcome: 'error' }, { notifyClosed: true });
+
+    const onAbort = () => settle({ outcome: 'error' }, { notifyClosed: false });
+    signal.addEventListener('abort', onAbort);
+
+    source.addEventListener(SERVER_CONNECTION_EVENTS.hello, () => {
+      if (settled) {
+        return;
+      }
+      if (hooks.onHello()) {
+        clearTimeout(helloTimer);
+      }
+    });
+  });

package/src/core/ticket.ts

@@ -0,0 +1,146 @@
+import type { FatalCause, SseClientOptions, SseLogger } from './types';
+
+// 티켓 층이 만드는 cause의 단일 원천 — fatal로 그대로 이어지므로 FatalCause의 부분집합이어야 합니다(satisfies가 강제)
+const TICKET_FAILURE_CAUSES = [
+  'auth_callback',
+] as const satisfies readonly FatalCause[];
+
+type TicketFailureCause = (typeof TICKET_FAILURE_CAUSES)[number];
+
+/**
+ * @description 티켓 발급 실패의 분류 — status 부재 = 네트워크성, cause = 네트워크가 아닌 실패의 출처.
+ * 워커 프로토콜이 이 객체를 그대로 실어 나르므로 직렬화 가능한 값만 담습니다.
+ */
+export interface TicketError {
+  status?: number;
+  // 와이어 너머의 신·구 버전이 미지 cause를 보낼 수 있습니다 — 코어는 아는 값만 동등 비교로 골라 씁니다
+  cause?: TicketFailureCause | (string & Record<never, never>);
+}
+
+export type TicketResult =
+  | { ok: true; ticket: string }
+  | { ok: false; error: TicketError };
+
+type ServerContractOptions = Pick<
+  SseClientOptions,
+  'baseUrl' | 'getAuthToken' | 'fetch' | 'logger'
+>;
+
+export const TICKET_TIMEOUT_MS = 10_000;
+
+export const TICKET_NETWORK_FAILURE: TicketResult = Object.freeze({
+  ok: false,
+  error: Object.freeze({}),
+});
+
+const TICKET_AUTH_CALLBACK_FAILURE: TicketResult = Object.freeze({
+  ok: false,
+  error: Object.freeze({ cause: 'auth_callback' as const }),
+});
+
+class AuthTokenError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'AuthTokenError';
+  }
+}
+
+const resolveAuthToken = async (
+  getAuthToken: ServerContractOptions['getAuthToken']
+): Promise<string | null> => {
+  try {
+    return await getAuthToken();
+  } catch (error) {
+    throw new AuthTokenError('getAuthToken threw', { cause: error });
+  }
+};
+
+const authHeaders = (token: string | null) =>
+  token === null ? undefined : { Authorization: `Bearer ${token}` };
+
+const hasTicket = (body: unknown): body is { data: { ticket: string } } => {
+  if (typeof body !== 'object' || body === null) {
+    return false;
+  }
+  const { data } = body as { data?: unknown };
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    typeof (data as { ticket?: unknown }).ticket === 'string'
+  );
+};
+
+/**
+ * @description 본문을 계약({ data: { ticket: string } } — 사내 기본 응답 스키마)으로 좁혀 값으로 돌려줍니다 —
+ * 파싱 실패(게이트웨이·프록시가 200으로 주는 HTML 등)와 형태 위반(ticket 부재)을 가르지 않습니다:
+ * 어느 쪽이든 서버가 응답한 본문 계약 위반이고, 경로 생존 증거라 status를 실어 네트워크성 연속 판정을 끊습니다.
+ * 이 분기는 stalled·fatal 어느 쪽에도 닿지 않는 유일한 침묵 실패라 warn을 남깁니다 — 서버 로그에도 흔적이
+ * 없는 실패(서버 입장에선 정상 200)여서 이 로그가 유일한 단서입니다.
+ */
+const parseTicketBody = async (
+  response: Response,
+  logger?: SseLogger
+): Promise<TicketResult> => {
+  const body: unknown = await response.json().catch(() => null);
+  if (!hasTicket(body)) {
+    logger?.warn(
+      `sse: 티켓 응답(${response.status}) 본문이 계약({ data: { ticket } })과 다릅니다 — 재시도는 계속합니다`
+    );
+    return { ok: false, error: { status: response.status } };
+  }
+  return { ok: true, ticket: body.data.ticket };
+};
+
+/**
+ * @description 연결 티켓을 발급합니다 — TTL 15s이므로 발급 즉시 연결해야 합니다
+ */
+export const issueTicket = async (
+  options: ServerContractOptions
+): Promise<TicketResult> => {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+
+  try {
+    const token = await resolveAuthToken(options.getAuthToken);
+    const response = await fetchImpl(`${options.baseUrl}/v1/events/ticket`, {
+      method: 'POST',
+      headers: authHeaders(token),
+    });
+
+    if (!response.ok) {
+      return { ok: false, error: { status: response.status } };
+    }
+
+    return await parseTicketBody(response, options.logger);
+  } catch (error) {
+    if (error instanceof AuthTokenError) {
+      // 정지 결정은 SseClient 몫이지만, 로그는 원인 예외가 있는 여기서 한 번만 — 워커 경로에선 탭 스코프라 유일한 기록입니다
+      options.logger?.error(
+        'sse: getAuthToken이 예외를 던져 멈춥니다 — 콜백은 실패 시 null을 반환해야 합니다',
+        error.cause
+      );
+      return TICKET_AUTH_CALLBACK_FAILURE;
+    }
+    return TICKET_NETWORK_FAILURE;
+  }
+};
+
+/**
+ * @description 티켓 발급에 시간 제한을 겁니다 — 타임아웃 이후 도착한 응답은 race가 이미 완료돼 무시됩니다
+ */
+export const issueTicketWithTimeout = async (
+  options: ServerContractOptions
+): Promise<TicketResult> => {
+  let ticketTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const ticketTimeout = new Promise<TicketResult>((resolve) => {
+    ticketTimer = setTimeout(
+      () => resolve(TICKET_NETWORK_FAILURE),
+      TICKET_TIMEOUT_MS
+    );
+  });
+
+  const result = await Promise.race([issueTicket(options), ticketTimeout]);
+  clearTimeout(ticketTimer);
+
+  return result;
+};

package/src/core/types.ts

@@ -0,0 +1,182 @@
+import type { BackoffOptions } from './backoff';
+
+// 상태 이름의 단일 원천 — 타입과 런타임 멤버십 검사가 같은 목록을 봅니다
+const SSE_STATUSES = [
+  'idle',
+  'connecting',
+  'open',
+  'reconnecting',
+  'closed',
+  'fatal',
+] as const;
+
+export type SseStatus = (typeof SSE_STATUSES)[number];
+
+/** @description postMessage 신뢰 경계용 — 버전이 다른 상대가 보낸 미지 상태값이 타입 보증을 깨지 않게 거릅니다 */
+export const isSseStatus = (value: unknown): value is SseStatus =>
+  (SSE_STATUSES as readonly unknown[]).includes(value);
+
+export type SseEventMap = Record<string, unknown>;
+
+// goaway 값의 단일 원천 — 타입과 런타임 검사가 같은 목록을 봅니다
+const GOAWAY_REASONS = [
+  'deploy',
+  'user_logout',
+  'maintenance',
+  'manual',
+] as const;
+const GOAWAY_ACTIONS = ['retry', 'close'] as const;
+
+export type GoawayReason = (typeof GOAWAY_REASONS)[number];
+export type GoawayAction = (typeof GOAWAY_ACTIONS)[number];
+
+/**
+ * @description 포트·스트림 너머의 값을 좁힙니다 — 미지 값은 없는 것으로 봅니다
+ */
+export const isGoawayReason = (value: unknown): value is GoawayReason =>
+  (GOAWAY_REASONS as readonly unknown[]).includes(value);
+
+export const isGoawayAction = (value: unknown): value is GoawayAction =>
+  (GOAWAY_ACTIONS as readonly unknown[]).includes(value);
+
+/**
+ * @description 서버가 연결을 닫으며 알려주는 사정 — SDK는 action만 보고, reason 대응은 소비처 몫입니다.
+ * 구버전 서버·잘린 프레임에서는 필드가 없을 수 있어 둘 다 선택입니다.
+ */
+export interface GoawayPayload {
+  reason?: GoawayReason;
+  action?: GoawayAction;
+}
+
+// fatal 값의 단일 원천 — 소비처가 원인별 안내(재로그인·한도·환경 차단)를 가르는 기준입니다
+const FATAL_CAUSES = [
+  'auth',
+  'auth_callback',
+  'rate_limit',
+  'blocked',
+  'config',
+  'unknown',
+] as const;
+
+export type FatalCause = (typeof FATAL_CAUSES)[number];
+
+/**
+ * @description 연결이 fatal로 멈춘 사유
+ * - auth = 티켓 401/403
+ * - auth_callback = getAuthToken이 던짐 (소비처 콜백 문제 — 콜백은 실패 시 throw 대신 null을 반환해야 합니다)
+ * - rate_limit = 티켓 429 ·
+ * - blocked = 워커 생성 차단(CSP 등)
+ * - config = EventSource 생성 실패(재시도해도 되살아나지 않습니다)
+ * - unknown = 연결 루프의 예상 못 한 예외.
+ *
+ * 회복(사유 해소 후 disconnect → connect)은 이 이벤트의 핸들러에서 시작하세요
+ * - status 리스너에서 끊으면 워커 경로에선 뒤따라오던 사유가 포트와 함께 버려집니다.
+ * 사유는 발화 순간의 구독자에게만 배달되므로 핸들러는 앱 루트에 고정하세요.
+ */
+export interface FatalPayload {
+  cause: FatalCause;
+  /** @description 티켓 발급 거부일 때만 — 서버가 준 HTTP 상태 코드 */
+  status?: number;
+}
+
+/**
+ * @description 재연결 등 SDK 수명주기 이벤트 — 도메인 이벤트 맵(M)과 병합되어 on()/wire()에 노출됩니다.
+ * `resync`·`goaway`·`fatal`·`stalled`는 SDK 예약 이벤트명이므로 서버 이벤트 맵에 같은 이름을 정의하지 않습니다.
+ */
+export type WithLifecycle<M extends object> = M & {
+  /**
+   * @description 재수립 후 "놓친 구간을 다시 조회하라"는 신호 — 끊긴 사이의 정합성은 REST 재조회로 메웁니다.
+   * (SDK 합성 — 와이어에 없는 이벤트입니다. 재연결 후 첫 hello에서 resync 이벤트가 발행됩니다)
+   */
+  resync: void;
+  /**
+   * @description 서버의 예고된 끊음 — `action: 'retry'`면 SDK가 즉시 재수립하고, `'close'`면 재연결 없이 닫습니다.
+   * 배포·로그아웃·점검처럼 에러가 아닐 수 있으니 안내는 close에서만 reason별로 고려하세요.
+   * (서버 발신 — 와이어의 `event: goaway`를 그대로 전달합니다)
+   */
+  goaway: GoawayPayload;
+  /**
+   * @description SDK의 포기 선언 — 재시도 없이 멈췄습니다. `cause`로 사유를 가르고,
+   * 사유 해소 후 disconnect() → connect()로 회복합니다.
+   * (SDK 합성 — 와이어에 없는 이벤트입니다. SDK가 실패를 판정해 발화합니다)
+   */
+  fatal: FatalPayload;
+  /**
+   * @description 네트워크 에러가 지속되고 있다는 진행형 통지 — fatal과 달리 재시도는 계속됩니다.
+   * 응답 status가 없는 실패(오프라인·CORS 차단·접속 거부 — 브라우저는 서로 구분해주지 않습니다)가
+   * hello에 닿지 못한 채 연속 5회 이어지는 순간 1회 발화합니다. 서버가 응답한 거부(5xx)는
+   * 네트워크 경로가 살아 있다는 증거라 세지 않고 연속을 끊습니다.
+   * 회복 시 별도 이벤트는 없습니다 — status가 open으로 바뀌는 것으로 알 수 있고, 판정은 그때 리셋됩니다.
+   * (SDK 합성 — 와이어에 없는 이벤트입니다. SDK가 연속 실패를 세어 발화합니다)
+   */
+  stalled: void;
+};
+
+export interface SseLogger {
+  warn(message: string, meta?: unknown): void;
+  error(message: string, meta?: unknown): void;
+}
+
+export interface SseClientOptions {
+  baseUrl: string;
+  /**
+   * @description 티켓 발급 요청에만 사용합니다 — null이면 인증 헤더 없이 요청합니다.
+   * 실패는 throw 대신 null로 알리세요 — 예외가 새어 나오면 재시도 없이 fatal(cause: 'auth_callback')로 멈춥니다.
+   */
+  getAuthToken: () => string | null | Promise<string | null>;
+  fetch?: typeof globalThis.fetch;
+  /** @description 워커 경로(sharedWorker 제공 시)에서는 적용되지 않습니다 — 스트림은 워커 스코프에서 만들어집니다 */
+  eventSource?: typeof EventSource;
+  backoff?: Partial<BackoffOptions>;
+  logger?: SseLogger;
+  /**
+   * @description 탭 간 연결 공유용 SharedWorker 팩토리 — 미제공 시 탭마다 직접 연결합니다.
+   * 워커 스크립트 URL은 소비처 번들러가 해석해야 하므로 인스턴스가 아니라 팩토리를 받습니다.
+   * @example () => new SharedWorker(new URL('@remember-web/sse/worker', import.meta.url), { name: 'rwp-sse', type: 'module' })
+   */
+  sharedWorker?: () => SharedWorker;
+}
+
+export type SseEventHandler<Payload> = (payload: Payload) => void;
+
+export type Unsubscribe = () => void;
+
+/**
+ * @description 리터럴 유니온에 흡수되지 않는 string 인터섹션으로, 자동완성을 유지한 채 임의 이름을 허용합니다
+ */
+export type SseEventName<M extends object> =
+  | (keyof WithLifecycle<M> & string)
+  | (string & Record<never, never>);
+
+/** @description 맵에 있는 이름이면 그 페이로드, 없으면 unknown — "미지 이벤트는 무시" 런타임과 타입을 일치시킵니다 */
+export type PayloadOf<
+  M extends object,
+  K extends string,
+> = K extends keyof WithLifecycle<M> ? WithLifecycle<M>[K] : unknown;
+
+/**
+ * @description 클라이언트 구현들이 공유하는 공개 표면 — M은 interface·type 어느 쪽 맵도 받도록 object로 제약합니다
+ */
+export interface SseClientLike<M extends object = SseEventMap> {
+  /** @description 타입 전용 마커 — M이 조건부 타입 안에만 있으면 wire() 등에서 M 추론이 불가능해집니다 */
+  readonly __eventMap?: M;
+  readonly status: SseStatus;
+  connect(): void;
+  disconnect(): void;
+  /**
+   * @description 이벤트 구독 — 해제 함수를 반환합니다. 구독은 connect()보다 먼저 걸어두세요.
+   * @param type 이벤트 이름. 도메인 이벤트 외 예약 4종 —
+   * `fatal`(SDK의 포기 선언 — 재시도 없이 멈춤, SDK 합성) ·
+   * `stalled`(재시도가 계속되는 진행형 통지, SDK 합성) ·
+   * `goaway`(서버의 예고된 끊음 — `action: 'close'`만 안내 대상, 서버 발신) ·
+   * `resync`(재수립 후 놓친 구간을 REST로 재조회하라는 신호, SDK 합성). 상세는 `WithLifecycle` 문서 참조.
+   * @param handler 이벤트 페이로드를 받는 콜백 — 발화 순간의 구독자에게만 배달됩니다
+   */
+  on<K extends SseEventName<M>>(
+    type: K,
+    handler: SseEventHandler<PayloadOf<M, K>>
+  ): Unsubscribe;
+  onStatus(listener: (status: SseStatus) => void): Unsubscribe;
+  /** @description 탭이 돌아올 때 자동으로 connect()를 부릅니다 — 반환값으로 떼세요 */
+  attachAutoResume(): Unsubscribe;
+}

package/src/core/wire.ts

@@ -0,0 +1,23 @@
+import type {
+  SseClientLike,
+  SseEventHandler,
+  Unsubscribe,
+  WithLifecycle,
+} from './types';
+
+export type WireHandlers<M extends object> = {
+  [K in keyof WithLifecycle<M>]?: SseEventHandler<WithLifecycle<M>[K]>;
+};
+
+/** @description 이벤트 핸들러 맵을 일괄 등록하고 전체 해제 함수를 반환합니다 — 호출 가능한 값만 등록합니다 */
+export function wire<M extends object>(
+  client: SseClientLike<M>,
+  handlers: WireHandlers<NoInfer<M>>
+): Unsubscribe {
+  const unsubscribers = Object.entries(handlers)
+    .filter(([, handler]) => typeof handler === 'function')
+    .map(([type, handler]) =>
+      client.on(type, handler as SseEventHandler<unknown>)
+    );
+  return () => unsubscribers.forEach((unsubscribe) => unsubscribe());
+}