@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/service-client/main/service-client.md

@@ -0,0 +1,206 @@
+# `ServiceClient`
+
+WebSocket 기반 서비스 클라이언트의 최상위 파사드 클래스. 내부적으로 `SocketProvider`, `ClientProtocolWrapper`, `ServiceTransport`, `EventClient`, `FileClient`를 조합한다.
+
+## When to use
+
+- ✅ `@simplysm/service-server`에 WebSocket으로 연결하여 RPC 호출, 이벤트, 파일, ORM 기능을 사용할 때
+- ✅ 재연결/하트비트가 자동 관리되는 WebSocket 클라이언트가 필요할 때
+- ❌ 서버 측 로직 구현 → `@simplysm/service-server`
+- ❌ 단순 HTTP REST 호출만 필요한 경우 → `fetch` API 직접 사용
+
+## Signature
+
+```typescript
+export class ServiceClient extends EventEmitter<ServiceClientEvents> {
+  constructor(
+    public readonly name: string,
+    public readonly options: ServiceConnectionOptions,
+  );
+  get connected(): boolean;
+  get hostUrl(): string;
+  getService<TService>(serviceName: string): ServiceProxy<TService>;
+  getEvent<TEventDef extends ServiceEventDef>(eventName: string): ClientEventProxy<TEventDef>;
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  send(
+    serviceName: string,
+    methodName: string,
+    params: unknown[],
+    progress?: ServiceProgress,
+  ): Promise<unknown>;
+  auth(token: string): Promise<void>;
+  addListener<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    info: TEventDef["$info"],
+    cb: (data: TEventDef["$data"]) => PromiseLike<void>,
+  ): Promise<string>;
+  removeListener(key: string): Promise<void>;
+  emitEvent<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+  uploadFile(
+    files: File[] | FileCollection | { name: string; data: BlobInput }[],
+  ): Promise<ServiceUploadResult[]>;
+  downloadFileBuffer(relPath: string): Promise<Bytes>;
+}
+```
+
+## Constructor Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | 클라이언트 식별자 (WebSocket URL 파라미터 및 HTTP 헤더로 전달됨) |
+| `options` | [`ServiceConnectionOptions`](../types/service-connection-options.md) | 연결 옵션 |
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `name` | property | `string` | 클라이언트 식별자 (읽기 전용) |
+| `options` | property | `ServiceConnectionOptions` | 연결 옵션 (읽기 전용) |
+| `connected` | getter | `boolean` | 현재 WebSocket 연결 상태 |
+| `hostUrl` | getter | `string` | HTTP 기본 URL (`http(s)://host:port`) |
+| `connect()` | method | `Promise<void>` | WebSocket 연결 시작 |
+| `close()` | method | `Promise<void>` | WebSocket 연결 종료 및 protocol dispose |
+| `auth(token)` | method | `Promise<void>` | 서버에 인증 토큰 전송. 재연결 시 자동 재인증됨 |
+| `getService<TService>(serviceName)` | method | `ServiceProxy<TService>` | 타입 안전한 서비스 프록시 반환 |
+| `getEvent<TEventDef>(eventName)` | method | `ClientEventProxy<TEventDef>` | 타입 안전한 이벤트 프록시 반환 |
+| `send(serviceName, methodName, params, progress?)` | method | `Promise<unknown>` | 서비스 메서드 원격 호출 |
+| `addListener(eventName, info, cb)` | method | `Promise<string>` | 서버 이벤트 구독. 연결 상태여야 함 |
+| `removeListener(key)` | method | `Promise<void>` | 서버 이벤트 구독 해제 |
+| `emitEvent(eventName, infoSelector, data)` | method | `Promise<void>` | 서버 이벤트 발행 |
+| `uploadFile(files)` | method | `Promise<ServiceUploadResult[]>` | 파일 업로드. `auth()` 호출 후 사용해야 함 |
+| `downloadFileBuffer(relPath)` | method | `Promise<Bytes>` | 파일 다운로드 (`Uint8Array` 반환) |
+
+## Events (EventEmitter)
+
+`ServiceClient`는 `EventEmitter<ServiceClientEvents>`를 상속한다. `.on()`/`.off()`로 이벤트를 구독한다.
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `request-progress` | `ServiceProgressState` | 요청 전송 progress |
+| `response-progress` | `ServiceProgressState` | 응답 수신 progress |
+| `server-progress` | `ServiceProgressState` | 서버 내부 처리 progress |
+| `state` | `"connected" \| "closed" \| "reconnecting"` | 연결 상태 변경 |
+
+## Related Types
+
+### `ServiceProxy`
+
+`TService`의 모든 메서드 반환 타입을 `Promise`로 래핑하는 유틸리티 타입. `getService<TService>()`의 반환 타입으로 사용된다.
+
+```typescript
+export type ServiceProxy<TService> = {
+  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+};
+```
+
+함수가 아닌 속성(`never`)은 타입에서 제외된다.
+
+## `createServiceClient`
+
+`ServiceClient` 팩토리 함수. `new ServiceClient(name, options)`와 동일하다.
+
+```typescript
+export function createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | 클라이언트 식별자 |
+| `options` | `ServiceConnectionOptions` | 연결 옵션 |
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { ServiceClient } from "@simplysm/service-client";
+
+const client = new ServiceClient("my-app", {
+  host: "localhost",
+  port: 3000,
+});
+
+await client.connect();
+const userSvc = client.getService<UserService>("User");
+const users = await userSvc.getList();
+await client.close();
+```
+
+### 전형 예제
+
+```typescript
+import { ServiceClient } from "@simplysm/service-client";
+
+const client = new ServiceClient("my-app", {
+  host: "api.example.com",
+  port: 443,
+  ssl: true,
+  maxReconnectCount: 5, // 재연결 5회 시도 후 포기
+});
+
+// 연결 상태 모니터링
+client.on("state", (state) => {
+  if (state === "reconnecting") {
+    // 재연결 시도 중 UI 피드백
+  }
+});
+
+await client.connect();
+await client.auth("jwt-token"); // 재연결 시 자동 재인증됨
+
+// 타입 안전한 서비스 호출
+const userSvc = client.getService<UserService>("User");
+const users = await userSvc.getList();
+
+// 이벤트 구독 (getEvent 프록시 방식 권장)
+const chatEvt = client.getEvent<typeof ChatEvent>("Chat");
+const key = await chatEvt.addListener({ roomId: "room-1" }, async (data) => {
+  // 재연결 시 자동 재구독됨
+});
+await chatEvt.removeListener(key);
+
+// 파일 업로드 (auth() 호출 후에만 가능)
+const results = await client.uploadFile([{ name: "file.txt", data: "hello" }]);
+
+// 파일 다운로드
+const bytes = await client.downloadFileBuffer("/files/report.pdf");
+
+await client.close();
+```
+
+## 🚫 Anti-patterns
+
+### auth() 없이 파일 업로드
+
+```typescript
+// ❌ auth() 호출 전에 uploadFile() 호출
+await client.connect();
+await client.uploadFile([...]); // Error: "인증 토큰이 없습니다..."
+
+// ✅ auth() 후 uploadFile() 호출
+await client.connect();
+await client.auth("token");
+await client.uploadFile([...]);
+```
+
+**근거**: `uploadFile()`은 내부적으로 `Authorization: Bearer {token}` 헤더를 사용하므로 인증 토큰이 필수이다.
+
+### 연결 안 됨 상태에서 addListener()
+
+```typescript
+// ❌ connect() 전에 addListener()
+const key = await client.addListener(...); // Error: "서버에 연결되지 않았습니다."
+
+// ✅ connect() 후 addListener() 또는 getEvent() 프록시 사용
+await client.connect();
+const key = await client.addListener(...);
+```
+
+**근거**: `addListener()`는 서버에 이벤트 등록 요청을 전송하므로 연결 상태여야 한다.

package/claude/references/sd-simplysm-v14/service-client/protocol/client-protocol-wrapper.md

@@ -0,0 +1,64 @@
+# `ClientProtocolWrapper`
+
+메시지 인코딩/디코딩 인터페이스. 데이터 크기가 30KB 이상이면 Web Worker로 처리를 오프로드한다. 팩토리 함수 `createClientProtocolWrapper`로 생성한다.
+
+## When to use
+
+- ✅ 메시지 인코딩/디코딩을 직접 제어하거나 Worker 오프로드 동작을 커스터마이징할 때
+- ❌ 일반적으로 `ServiceClient`가 내부적으로 생성·관리한다. 직접 생성은 커스텀 전송 계층 구현 시에만 필요하다.
+
+```typescript
+export interface ClientProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `encode(uuid, message)` | method | `Promise<{ chunks: Bytes[]; totalSize: number }>` | 메시지를 바이너리 청크로 인코딩. 큰 데이터는 Worker로 오프로드 |
+| `decode(bytes)` | method | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | 바이너리를 메시지로 디코딩. 큰 데이터는 Worker로 오프로드 (zero-copy 전송) |
+| `dispose()` | method | `void` | 내부 `ServiceProtocol`과 Worker resolver 맵 정리 |
+
+## `createClientProtocolWrapper`
+
+`ClientProtocolWrapper` 팩토리 함수.
+
+```typescript
+export function createClientProtocolWrapper(protocol: ServiceProtocol): ClientProtocolWrapper;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `protocol` | `ServiceProtocol` | `@simplysm/service-common`의 `createServiceProtocol()`로 생성한 프로토콜 인스턴스 |
+
+내부 동작:
+- 임계값: 30KB (`30 * 1024` bytes)
+- Worker가 지원되지 않는 환경에서는 메인 스레드에서 처리
+- Worker는 모듈 스코프 싱글턴으로 공유됨 (`createClientProtocolWrapper` 여러 번 호출해도 Worker는 하나)
+- Worker 작업은 60초 타임아웃 후 자동 reject (메모리 누수 방지)
+- `decode` 시 Worker로 `ArrayBuffer` 소유권 이전 (zero-copy)
+
+**Worker 생성 패턴 제약:**
+
+Worker 생성 시 반드시 `new Worker(new URL("...", import.meta.url))` 직접 패턴을 사용해야 한다. sd-cli의 esbuild Worker 번들링 플러그인(`sd-worker-bundle`)이 AST에서 이 패턴만 인식하여 Worker 파일을 별도 번들로 분리한다. 래퍼 함수로 감싸면 플러그인이 인식하지 못하고 브라우저에서 404 에러가 발생한다.
+
+## Usage
+
+```typescript
+import { createClientProtocolWrapper } from "@simplysm/service-client";
+import { createServiceProtocol } from "@simplysm/service-common";
+
+const protocol = createServiceProtocol();
+const wrapper = createClientProtocolWrapper(protocol);
+
+const { chunks, totalSize } = await wrapper.encode("uuid-1", { name: "User.getList", body: [] });
+// chunks: Bytes[] — 전송할 청크 배열
+// totalSize: number — 전체 크기 (progress 표시용)
+
+// 사용 완료 후 반드시 정리
+wrapper.dispose();
+```

package/claude/references/sd-simplysm-v14/service-client/transport/service-transport.md

@@ -0,0 +1,68 @@
+# `ServiceTransport`
+
+요청-응답 매핑, progress 중계, 서버 이벤트 디스패치를 담당하는 인터페이스. 팩토리 함수 `createServiceTransport`로 생성한다.
+
+## When to use
+
+- ✅ 요청-응답 매핑과 progress 중계를 직접 제어하는 커스텀 계층을 구현할 때
+- ❌ 일반적으로 `ServiceClient`가 내부적으로 생성·관리한다. 직접 생성이 필요한 경우는 드물다.
+
+```typescript
+export interface ServiceTransport {
+  on<K extends keyof ServiceTransportEvents & string>(
+    type: K,
+    listener: (data: ServiceTransportEvents[K]) => void,
+  ): void;
+  off<K extends keyof ServiceTransportEvents & string>(
+    type: K,
+    listener: (data: ServiceTransportEvents[K]) => void,
+  ): void;
+  send(message: ServiceClientMessage, progress?: ServiceProgress): Promise<unknown>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `on(type, listener)` | method | `void` | 이벤트 리스너 등록 |
+| `off(type, listener)` | method | `void` | 이벤트 리스너 제거 |
+| `send(message, progress?)` | method | `Promise<unknown>` | 서버에 메시지 전송하고 응답 대기 |
+
+## Related Types
+
+### `ServiceTransportEvents`
+
+`ServiceTransport`에서 발생하는 이벤트 타입 맵.
+
+```typescript
+export interface ServiceTransportEvents {
+  event: { keys: string[]; data: unknown };
+}
+```
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `event` | `{ keys: string[]; data: unknown }` | 서버에서 발행된 이벤트 수신 |
+
+## `createServiceTransport`
+
+`ServiceTransport` 팩토리 함수.
+
+```typescript
+export function createServiceTransport(
+  socket: SocketProvider,
+  protocol: ClientProtocolWrapper,
+): ServiceTransport;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `socket` | [`SocketProvider`](./socket-provider.md) | WebSocket 소켓 제공자 |
+| `protocol` | [`ClientProtocolWrapper`](../protocol/client-protocol-wrapper.md) | 인코딩/디코딩 래퍼 |
+
+내부 동작:
+- `uuid` 기반 요청-응답 `Map`으로 비동기 응답을 매핑
+- 소켓 `closed`/`reconnecting` 상태 시 대기 중인 모든 요청을 reject
+- 분할 메시지의 progress 상태를 추적하여 완료 시 100% 이벤트 전송
+- 소켓 `message` 이벤트를 수신하여 `progress`, `response`, `error`, `evt:on` 타입으로 분기 처리

package/claude/references/sd-simplysm-v14/service-client/transport/socket-provider.md

@@ -0,0 +1,100 @@
+# `SocketProvider`
+
+WebSocket 연결, 재연결, 하트비트를 관리하는 인터페이스. 팩토리 함수 `createSocketProvider`로 생성한다.
+
+## When to use
+
+- ✅ WebSocket 연결/재연결/하트비트를 직접 제어하는 커스텀 전송 계층을 구현할 때
+- ❌ 일반적으로 `ServiceClient`가 내부적으로 생성·관리한다. 직접 생성은 `ServiceClient` 없이 독립 WebSocket 통신이 필요한 경우에만 사용한다.
+
+```typescript
+export interface SocketProvider {
+  readonly clientName: string;
+  readonly connected: boolean;
+  on<K extends keyof SocketProviderEvents & string>(
+    type: K,
+    listener: (data: SocketProviderEvents[K]) => void,
+  ): void;
+  off<K extends keyof SocketProviderEvents & string>(
+    type: K,
+    listener: (data: SocketProviderEvents[K]) => void,
+  ): void;
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  send(data: Bytes): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `clientName` | property | `string` | 클라이언트 식별자 (읽기 전용) |
+| `connected` | getter | `boolean` | 현재 연결 상태 |
+| `on(type, listener)` | method | `void` | 이벤트 리스너 등록 |
+| `off(type, listener)` | method | `void` | 이벤트 리스너 제거 |
+| `connect()` | method | `Promise<void>` | WebSocket 연결 시작 |
+| `close()` | method | `Promise<void>` | WebSocket 연결 종료 |
+| `send(data)` | method | `Promise<void>` | 바이너리 데이터 전송. 연결 복구 대기 후 전송 |
+
+## Related Types
+
+### `SocketProviderEvents`
+
+`SocketProvider`에서 발생하는 이벤트 타입 맵.
+
+```typescript
+export interface SocketProviderEvents {
+  message: Bytes;
+  state: "connected" | "closed" | "reconnecting";
+}
+```
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `message` | `Bytes` | 서버로부터 바이너리 메시지 수신 |
+| `state` | `"connected" \| "closed" \| "reconnecting"` | 연결 상태 변경 |
+
+## `createSocketProvider`
+
+`SocketProvider` 팩토리 함수.
+
+```typescript
+export function createSocketProvider(
+  url: string,
+  clientName: string,
+  maxReconnectCount: number,
+): SocketProvider;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | WebSocket 서버 URL (`ws://` 또는 `wss://`) |
+| `clientName` | `string` | 클라이언트 식별자 (URL 파라미터 `clientName`으로 전달됨) |
+| `maxReconnectCount` | `number` | 최대 재연결 횟수. `0`이면 재연결 안 함 |
+
+내부 동작:
+- 하트비트: 5초마다 ping 전송, 30초 응답 없으면 재연결 시도
+- 재연결: 연결 끊김 시 3초 간격으로 `maxReconnectCount`회 재시도
+- Node.js 환경에서 `globalThis.WebSocket`이 없으면 `ws` 패키지로 폴리필
+- ping/pong은 1바이트 패킷(ping: `0x01`, pong: `0x02`)으로 처리
+
+## Usage
+
+```typescript
+import { createSocketProvider } from "@simplysm/service-client";
+
+const socket = createSocketProvider("ws://localhost:3000/ws", "my-app", 10);
+
+socket.on("state", (state) => {
+  console.log("소켓 상태:", state); // "connected" | "closed" | "reconnecting"
+});
+
+socket.on("message", (bytes) => {
+  console.log("메시지 수신:", bytes.length, "bytes");
+});
+
+await socket.connect();
+await socket.send(new Uint8Array([1, 2, 3]));
+await socket.close();
+```

package/claude/references/sd-simplysm-v14/service-client/types/blob-input.md

@@ -0,0 +1,7 @@
+# BlobInput
+
+Blob constructor가 허용하는 데이터 타입. DOM `BlobPart`를 대체하여 Node.js / 브라우저 양쪽에서 typecheck가 통과하도록 한다.
+
+```typescript
+export type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string;
+```

package/claude/references/sd-simplysm-v14/service-client/types/browser-worker.md

@@ -0,0 +1,47 @@
+# BrowserWorker
+
+Web Worker 최소 인터페이스. DOM lib 없이도 타입체크가 통과하도록 하는 추상 타입이다.
+
+```typescript
+export interface BrowserWorker {
+  onmessage: ((event: MessageEvent) => void) | null;
+  onerror: ((event: Event) => void) | null;
+  postMessage(message: unknown, transfer?: unknown[]): void;
+  terminate(): void;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `onmessage` | `((event: MessageEvent) => void) \| null` | 메시지 수신 핸들러 |
+| `onerror` | `((event: Event) => void) \| null` | 에러 핸들러 |
+| `postMessage(message, transfer?)` | `void` | Worker에 메시지 전송 |
+| `terminate()` | `void` | Worker 종료 |
+
+## Related Functions
+
+### `isBrowserWorkerSupported`
+
+DOM Worker API 지원 여부를 확인한다. `"Worker" in globalThis`로 판별한다.
+
+```typescript
+export function isBrowserWorkerSupported(): boolean;
+```
+
+### `isNodeWorkerSupported`
+
+Node.js `worker_threads` 지원 여부를 확인한다. `process.versions.node` 존재 여부로 판별한다.
+
+```typescript
+export function isNodeWorkerSupported(): boolean;
+```
+
+### `isWorkerSupported`
+
+Worker 오프로딩 지원 여부를 확인한다. `isBrowserWorkerSupported() || isNodeWorkerSupported()`를 반환한다.
+
+```typescript
+export function isWorkerSupported(): boolean;
+```

package/claude/references/sd-simplysm-v14/service-client/types/file-collection.md

@@ -0,0 +1,21 @@
+# FileCollection
+
+File 컬렉션 인터페이스. DOM `FileList`를 대체하며 브라우저 `FileList`와 구조적으로 호환된다.
+
+```typescript
+export interface FileCollection {
+  readonly length: number;
+  item(index: number): File | null;
+  [index: number]: File;
+  [Symbol.iterator](): IterableIterator<File>;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `length` | `number` | 파일 개수 (읽기 전용) |
+| `item(index)` | `File \| null` | 인덱스로 File 반환 |
+| `[index]` | `File` | 인덱스 접근자 |
+| `[Symbol.iterator]()` | `IterableIterator<File>` | for-of 이터레이션 지원 |

package/claude/references/sd-simplysm-v14/service-client/types/service-connection-options.md

@@ -0,0 +1,22 @@
+# ServiceConnectionOptions
+
+서비스 서버에 연결할 때 사용하는 옵션 인터페이스.
+
+```typescript
+export interface ServiceConnectionOptions {
+  port: number;
+  host: string;
+  ssl?: boolean;
+  /** 0으로 설정하면 재연결을 비활성화하고 즉시 연결을 끊음 */
+  maxReconnectCount?: number;
+}
+```
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `port` | `number` | required | 서버 포트 번호 |
+| `host` | `string` | required | 서버 호스트 주소 |
+| `ssl` | `boolean` | optional | HTTPS/WSS 사용 여부. 기본값 `false` |
+| `maxReconnectCount` | `number` | optional | 최대 재연결 횟수. `0`이면 재연결 비활성화. `ServiceClient` 기본값 `10` |

package/claude/references/sd-simplysm-v14/service-client/types/service-progress.md

@@ -0,0 +1,39 @@
+# ServiceProgress
+
+요청/응답/서버 단계별 progress 콜백을 담는 컨테이너 인터페이스.
+
+```typescript
+export interface ServiceProgress {
+  request?: (s: ServiceProgressState) => void;
+  response?: (s: ServiceProgressState) => void;
+  server?: (s: ServiceProgressState) => void;
+}
+```
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `request` | `(s: ServiceProgressState) => void` | optional | 클라이언트 → 서버 전송 progress |
+| `response` | `(s: ServiceProgressState) => void` | optional | 서버 → 클라이언트 수신 progress |
+| `server` | `(s: ServiceProgressState) => void` | optional | 서버 내부 처리 progress |
+
+## Related Types
+
+### `ServiceProgressState`
+
+progress 콜백에 전달되는 상태 객체.
+
+```typescript
+export interface ServiceProgressState {
+  uuid: string;
+  totalSize: number;
+  completedSize: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `uuid` | `string` | 요청 식별자 |
+| `totalSize` | `number` | 전체 크기 (bytes) |
+| `completedSize` | `number` | 완료된 크기 (bytes) |