@simplysm/service-client 13.0.96 → 13.0.98

package/README.md

@@ -1,18 +1,48 @@
 # @simplysm/service-client
 
-WebSocket 기반 RPC 서비스 클라이언트. 자동 재연결, 이벤트 구독, 파일 업로드/다운로드, ORM 연동을 지원한다.
+Service module (client) -- WebSocket-based service client for communicating with `@simplysm/service-server`.
 
-## 설치
+## Installation
 
 ```bash
 npm install @simplysm/service-client
 ```
 
-**의존성:** `@simplysm/core-common`, `@simplysm/orm-common`, `@simplysm/service-common`
+## Exports
 
-## 주요 사용법
+```typescript
+import {
+  // Main
+  ServiceClient,
+  createServiceClient,
+  type ServiceProxy,
+  // Types
+  type ServiceConnectionOptions,
+  type ServiceProgress,
+  type ServiceProgressState,
+  // Transport
+  type SocketProvider,
+  type SocketProviderEvents,
+  createSocketProvider,
+  type ServiceTransport,
+  type ServiceTransportEvents,
+  createServiceTransport,
+  // Protocol
+  type ClientProtocolWrapper,
+  createClientProtocolWrapper,
+  // Features
+  type EventClient,
+  createEventClient,
+  type FileClient,
+  createFileClient,
+  type OrmConnectOptions,
+  type OrmClientConnector,
+  createOrmClientConnector,
+  OrmClientDbContextExecutor,
+} from "@simplysm/service-client";
+```
 
-### 클라이언트 생성 및 연결
+## Quick Start
 
 ```typescript
 import { createServiceClient } from "@simplysm/service-client";
@@ -20,293 +50,33 @@ import { createServiceClient } from "@simplysm/service-client";
 const client = createServiceClient("my-app", {
   host: "localhost",
   port: 3000,
-  ssl: false,
-  maxReconnectCount: 10, // 0이면 재연결 비활성화
 });
 
 await client.connect();
-// ... 사용 ...
-await client.close();
-```
-
-`ServiceClient` 클래스를 직접 사용할 수도 있다.
-
-```typescript
-import { ServiceClient } from "@simplysm/service-client";
-
-const client = new ServiceClient("my-app", {
-  host: "localhost",
-  port: 3000,
-});
-```
-
-### 서비스 호출 (RPC)
-
-```typescript
-// 타입 안전한 서비스 프록시
-const userService = client.getService<UserService>("User");
-const users = await userService.findAll();
-const user = await userService.findById(1);
-
-// 직접 호출
-const result = await client.send("User", "findById", [1]);
-
-// 진행률 콜백과 함께 호출
-const result = await client.send("User", "exportData", [], {
-  request: (state) => {
-    // state.completedSize / state.totalSize 로 진행률 계산
-  },
-  response: (state) => {
-    // state.completedSize / state.totalSize 로 진행률 계산
-  },
-});
-```
-
-### 인증
-
-```typescript
-await client.auth(jwtToken);
-```
 
-재연결 시 인증 토큰이 자동으로 재전송된다.
-
-### 이벤트 구독
-
-```typescript
-import { defineEvent } from "@simplysm/service-common";
-
-const OrderCreated = defineEvent<{ shopId: string }, { orderId: string; amount: number }>(
-  "order-created"
-);
-
-// 이벤트 구독 (info로 필터 조건 전달)
-const key = await client.addListener(
-  OrderCreated,
-  { shopId: "shop-1" },
-  async (data) => {
-    // data: { orderId: string; amount: number }
-  }
-);
-
-// 이벤트 구독 해제
-await client.removeListener(key);
-
-// 이벤트 발행 (서버를 통해 다른 클라이언트에 전달)
-await client.emitEvent(
-  OrderCreated,
-  (info) => info.shopId === "shop-1",
-  { orderId: "order-123", amount: 50000 }
-);
-```
-
-재연결 시 이벤트 리스너가 서버에 자동으로 재등록된다.
-
-### 파일 업로드/다운로드
-
-파일 업로드는 `auth()`로 인증한 후에만 사용할 수 있다.
-
-```typescript
-// 업로드 (인증 필수)
-await client.auth(jwtToken);
-const results = await client.uploadFile(fileInput.files);
-// results: ServiceUploadResult[] (path, filename, size)
-
-// { name, data } 객체 배열도 지원
-await client.uploadFile([
-  { name: "report.xlsx", data: uint8ArrayData },
-]);
-
-// 다운로드 (Uint8Array 반환)
-const buffer = await client.downloadFileBuffer("uploads/report.xlsx");
-```
-
-### 진행률 추적
-
-```typescript
-// 이벤트 기반 (모든 요청/응답에 대해)
-client.on("request-progress", ({ uuid, totalSize, completedSize }) => {
-  // 요청 전송 진행률
-});
-
-client.on("response-progress", ({ uuid, totalSize, completedSize }) => {
-  // 응답 수신 진행률
-});
+// Authenticate
+await client.auth(token);
 
-// 연결 상태 변경
-client.on("state", (state) => {
-  // "connected" | "closed" | "reconnecting"
-});
+// Call a service method
+const service = client.getService<MyServiceType>("MyService");
+const result = await service.someMethod("arg1", "arg2");
 
-// 서버 HMR 리로드 알림
-client.on("reload", (changedFiles) => {
-  // changedFiles: Set<string>
-  location.reload();
+// Listen for events
+await client.addListener(SomeEvent, { id: 1 }, async (data) => {
+  // handle event
 });
-```
-
-### ORM 클라이언트 연동
-
-서버의 ORM 서비스를 통해 클라이언트에서 DbContext를 사용한다.
-
-```typescript
-import { createOrmClientConnector } from "@simplysm/service-client";
-
-const ormConnector = createOrmClientConnector(client);
-
-// 트랜잭션 포함 연결
-const result = await ormConnector.connect(
-  {
-    dbContextDef: MyDb,
-    connOpt: { configName: "main" },
-    // 선택적: DB/스키마 오버라이드
-    // dbContextOpt: { database: "mydb", schema: "dbo" },
-  },
-  async (db) => {
-    return await db.user().execute();
-  }
-);
-
-// 트랜잭션 없이 연결
-const result = await ormConnector.connectWithoutTransaction(
-  { dbContextDef: MyDb, connOpt: { configName: "main" } },
-  async (db) => {
-    return await db.user().execute();
-  }
-);
-```
-
-## API 레퍼런스
-
-### `createServiceClient(name, options)`
-
-`ServiceClient` 인스턴스를 생성하는 팩토리 함수.
-
-| 파라미터 | 타입 | 설명 |
-|---------|------|------|
-| `name` | `string` | 클라이언트 식별 이름 |
-| `options` | `ServiceConnectionOptions` | 연결 설정 |
-
-### `ServiceClient`
-
-`EventEmitter<ServiceClientEvents>`를 확장한 메인 클라이언트 클래스.
-
-**속성:**
-
-| 이름 | 타입 | 설명 |
-|------|------|------|
-| `name` | `string` | 클라이언트 이름 (읽기 전용) |
-| `options` | `ServiceConnectionOptions` | 연결 설정 (읽기 전용) |
-| `connected` | `boolean` | 현재 연결 상태 |
-| `hostUrl` | `string` | `http(s)://host:port` 형식 URL |
-
-**메서드:**
-
-| 메서드 | 반환 | 설명 |
-|--------|------|------|
-| `connect()` | `Promise<void>` | 서버에 연결 |
-| `close()` | `Promise<void>` | 연결 종료 |
-| `auth(token)` | `Promise<void>` | JWT 토큰으로 인증 |
-| `send(serviceName, methodName, params, progress?)` | `Promise<unknown>` | RPC 호출 |
-| `getService<T>(serviceName)` | `ServiceProxy<T>` | 타입 안전 서비스 프록시 생성 |
-| `addListener(eventDef, info, cb)` | `Promise<string>` | 이벤트 구독 (키 반환) |
-| `removeListener(key)` | `Promise<void>` | 이벤트 구독 해제 |
-| `emitEvent(eventDef, infoSelector, data)` | `Promise<void>` | 이벤트 발행 |
-| `uploadFile(files)` | `Promise<ServiceUploadResult[]>` | 파일 업로드 (인증 필수) |
-| `downloadFileBuffer(relPath)` | `Promise<Bytes>` | 파일 다운로드 |
-
-**이벤트:**
-
-| 이벤트 | 데이터 타입 | 설명 |
-|--------|-----------|------|
-| `request-progress` | `ServiceProgressState` | 요청 전송 진행률 |
-| `response-progress` | `ServiceProgressState` | 응답 수신 진행률 |
-| `state` | `"connected" \| "closed" \| "reconnecting"` | 연결 상태 변경 |
-| `reload` | `Set<string>` | 서버 HMR 리로드 알림 |
-
-### `ServiceProxy<TService>`
 
-서비스의 모든 메서드 반환 타입을 `Promise`로 감싸는 유틸리티 타입.
+// Upload files
+const results = await client.uploadFile(fileList);
 
-```typescript
-type ServiceProxy<TService> = {
-  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
-    ? (...args: P) => Promise<Awaited<R>>
-    : never;
-};
-```
-
-### `ServiceConnectionOptions`
-
-```typescript
-interface ServiceConnectionOptions {
-  port: number;
-  host: string;
-  ssl?: boolean;               // HTTPS/WSS 사용 (기본: false)
-  maxReconnectCount?: number;  // 최대 재연결 시도 (기본: 10, 0=비활성화)
-}
-```
-
-### `ServiceProgress` / `ServiceProgressState`
-
-```typescript
-interface ServiceProgress {
-  request?: (s: ServiceProgressState) => void;
-  response?: (s: ServiceProgressState) => void;
-}
-
-interface ServiceProgressState {
-  uuid: string;
-  totalSize: number;
-  completedSize: number;
-}
-```
-
-### `createOrmClientConnector(serviceClient)`
-
-`OrmClientConnector` 인스턴스를 생성한다.
-
-**`OrmClientConnector` 메서드:**
-
-| 메서드 | 설명 |
-|--------|------|
-| `connect(config, callback)` | 트랜잭션 포함 DB 연결. 외래 키 제약 위반 시 친화적 에러 메시지 제공 |
-| `connectWithoutTransaction(config, callback)` | 트랜잭션 없이 DB 연결 |
-
-### `OrmConnectOptions<TDef>`
-
-```typescript
-interface OrmConnectOptions<TDef extends DbContextDef<any, any, any>> {
-  dbContextDef: TDef;
-  connOpt: DbConnOptions & { configName: string };
-  dbContextOpt?: {
-    database: string;
-    schema: string;
-  };
-}
+// Close
+await client.close();
 ```
 
-### 하위 모듈
-
-다음 인터페이스와 팩토리 함수도 export되며, 커스텀 구성이 필요할 때 사용한다.
-
-| Export | 설명 |
-|--------|------|
-| `createSocketProvider(url, clientName, maxReconnectCount)` | WebSocket 연결 관리 (하트비트, 재연결) |
-| `SocketProvider` | 소켓 프로바이더 인터페이스 |
-| `createServiceTransport(socket, protocol)` | 요청/응답 매칭 및 메시지 라우팅 |
-| `ServiceTransport` | 트랜스포트 인터페이스 |
-| `createClientProtocolWrapper(protocol)` | Worker 기반 인코딩/디코딩 래퍼 |
-| `ClientProtocolWrapper` | 프로토콜 래퍼 인터페이스 |
-| `createEventClient(transport)` | 이벤트 구독/발행 관리 |
-| `EventClient` | 이벤트 클라이언트 인터페이스 |
-| `createFileClient(hostUrl, clientName)` | HTTP 기반 파일 업로드/다운로드 |
-| `FileClient` | 파일 클라이언트 인터페이스 |
-| `OrmClientDbContextExecutor` | `DbContextExecutor` 구현체 (RPC 경유) |
-
-## 내부 동작
+## Documentation
 
-- **하트비트:** 5초 간격 ping 전송, 30초 타임아웃 시 연결 끊김 감지 후 자동 재연결
-- **재연결:** 3초 간격 재시도, 재연결 성공 시 인증 토큰 재전송 및 이벤트 자동 재구독
-- **대용량 메시지:** Web Worker에서 인코딩/디코딩 (30KB 이상 또는 Uint8Array 포함 시)
-- **프로토콜:** 3MB 초과 시 300KB 청크 자동 분할, 진행률 이벤트 발생
-- **소켓 종료 시:** 모든 대기 중인 요청이 자동으로 reject되어 메모리 누수 방지
+- [Types](docs/types.md)
+- [Transport](docs/transport.md)
+- [Protocol](docs/protocol.md)
+- [Features](docs/features.md)
+- [ServiceClient](docs/service-client.md)

package/docs/features.md

@@ -0,0 +1,142 @@
+# Features
+
+## EventClient
+
+Client-side event subscription manager. Handles adding/removing event listeners and auto-resubscription on reconnect.
+
+### `EventClient`
+
+```typescript
+interface EventClient {
+  addListener<TInfo, TData>(
+    eventDef: ServiceEventDef<TInfo, TData>,
+    info: TInfo,
+    cb: (data: TData) => PromiseLike<void>,
+  ): Promise<string>;
+
+  removeListener(key: string): Promise<void>;
+
+  emit<TInfo, TData>(
+    eventDef: ServiceEventDef<TInfo, TData>,
+    infoSelector: (item: TInfo) => boolean,
+    data: TData,
+  ): Promise<void>;
+
+  resubscribeAll(): Promise<void>;
+}
+```
+
+### `createEventClient`
+
+```typescript
+function createEventClient(transport: ServiceTransport): EventClient;
+```
+
+**Behavior:**
+- `addListener` registers on the server and stores locally for reconnect recovery
+- `removeListener` removes from local map and sends removal request to server
+- `emit` queries the server for matching listener infos, then sends event to matching keys
+- `resubscribeAll` re-registers all local listeners on the server (called on reconnect)
+
+---
+
+## FileClient
+
+HTTP-based file upload/download client.
+
+### `FileClient`
+
+```typescript
+interface FileClient {
+  download(relPath: string): Promise<Bytes>;
+  upload(
+    files: File[] | FileList | { name: string; data: BlobPart }[],
+    authToken: string,
+  ): Promise<ServiceUploadResult[]>;
+}
+```
+
+### `createFileClient`
+
+```typescript
+function createFileClient(hostUrl: string, clientName: string): FileClient;
+```
+
+**Behavior:**
+- `download` fetches a file via HTTP GET and returns it as `Uint8Array`
+- `upload` sends files via multipart form POST to `/upload` with auth token in headers
+
+---
+
+## ORM Features
+
+### `OrmConnectOptions`
+
+Configuration for ORM database connections via the service client.
+
+```typescript
+interface OrmConnectOptions<TDef extends DbContextDef<any, any, any>> {
+  dbContextDef: TDef;
+  connOpt: DbConnOptions & { configName: string };
+  dbContextOpt?: {
+    database: string;
+    schema: string;
+  };
+}
+```
+
+### `OrmClientConnector`
+
+Manages ORM database connections through the service client.
+
+```typescript
+interface OrmClientConnector {
+  connect<TDef extends DbContextDef<any, any, any>, R>(
+    config: OrmConnectOptions<TDef>,
+    callback: (db: DbContextInstance<TDef>) => Promise<R> | R,
+  ): Promise<R>;
+
+  connectWithoutTransaction<TDef extends DbContextDef<any, any, any>, R>(
+    config: OrmConnectOptions<TDef>,
+    callback: (db: DbContextInstance<TDef>) => Promise<R> | R,
+  ): Promise<R>;
+}
+```
+
+### `createOrmClientConnector`
+
+```typescript
+function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector;
+```
+
+**Behavior:**
+- `connect` creates a database context and executes the callback within a transaction
+- `connectWithoutTransaction` creates a database context without transaction wrapping
+- Foreign key constraint violations are caught and re-thrown with a user-friendly message
+
+### `OrmClientDbContextExecutor`
+
+Implements `DbContextExecutor` by delegating all database operations to the remote `OrmService` via WebSocket.
+
+```typescript
+class OrmClientDbContextExecutor implements DbContextExecutor {
+  constructor(client: ServiceClient, opt: DbConnOptions & { configName: string });
+
+  async getInfo(): Promise<{ dialect: Dialect; database?: string; schema?: string }>;
+  async connect(): Promise<void>;
+  async beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  async commitTransaction(): Promise<void>;
+  async rollbackTransaction(): Promise<void>;
+  async close(): Promise<void>;
+  async executeDefs<T = Record<string, unknown>>(
+    defs: QueryDef[],
+    options?: (ResultMeta | undefined)[],
+  ): Promise<T[][]>;
+  async executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]>;
+  async bulkInsert(
+    tableName: string,
+    columnDefs: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```

package/docs/protocol.md

@@ -0,0 +1,39 @@
+# Protocol
+
+Client-side protocol wrapper that handles message encoding/decoding with optional Web Worker offloading for large payloads.
+
+## `ClientProtocolWrapper`
+
+```typescript
+interface ClientProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+}
+```
+
+## `createClientProtocolWrapper`
+
+Create a client protocol wrapper instance.
+
+```typescript
+function createClientProtocolWrapper(protocol: ServiceProtocol): ClientProtocolWrapper;
+```
+
+**Parameters:**
+- `protocol` -- A `ServiceProtocol` instance (from `@simplysm/service-common`)
+
+**Behavior:**
+- Messages smaller than 30KB are processed on the main thread
+- Larger messages are offloaded to a Web Worker for encoding/decoding
+- Worker is automatically initialized as a lazy singleton
+- Worker tasks that do not complete within 60s are rejected (prevents memory leaks)
+- Falls back to main-thread processing when `Worker` is not available (e.g., SSR)
+
+**Worker delegation heuristics for encoding:**
+- `Uint8Array` body: always use worker
+- String body longer than 30KB: use worker
+- Array body with >100 elements or containing `Uint8Array`: use worker
+
+**Worker delegation heuristics for decoding:**
+- Byte size > 30KB: use worker
+- After worker decoding, `transfer.decode()` is applied to restore class instances (e.g., `DateTime`)

package/docs/service-client.md

@@ -0,0 +1,210 @@
+# ServiceClient
+
+Main client class that orchestrates all service communication modules.
+
+```typescript
+import { ServiceClient, createServiceClient, type ServiceProxy } from "@simplysm/service-client";
+```
+
+## `ServiceProxy<TService>`
+
+Type transformer that wraps all method return types of `TService` with `Promise`.
+
+```typescript
+type ServiceProxy<TService> = {
+  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+};
+```
+
+## Class: `ServiceClient`
+
+Extends `EventEmitter<ServiceClientEvents>`.
+
+### Events
+
+```typescript
+interface ServiceClientEvents {
+  "request-progress": ServiceProgressState;
+  "response-progress": ServiceProgressState;
+  "state": "connected" | "closed" | "reconnecting";
+  "reload": Set<string>;
+}
+```
+
+### Constructor
+
+```typescript
+constructor(name: string, options: ServiceConnectionOptions)
+```
+
+- `name` -- Client name (used for identification on the server)
+- `options` -- Connection options
+
+### Properties
+
+#### `connected`
+
+```typescript
+get connected(): boolean;
+```
+
+#### `hostUrl`
+
+```typescript
+get hostUrl(): string;
+```
+
+Returns the HTTP(S) URL of the server (e.g., `"https://localhost:3000"`).
+
+### Methods
+
+#### `connect`
+
+Connect to the server via WebSocket.
+
+```typescript
+async connect(): Promise<void>;
+```
+
+#### `close`
+
+Close the WebSocket connection.
+
+```typescript
+async close(): Promise<void>;
+```
+
+#### `auth`
+
+Authenticate with the server using a JWT token.
+
+```typescript
+async auth(token: string): Promise<void>;
+```
+
+#### `getService`
+
+Create a type-safe proxy for calling remote service methods.
+
+```typescript
+getService<TService>(serviceName: string): ServiceProxy<TService>;
+```
+
+**Example:**
+```typescript
+const userService = client.getService<UserServiceType>("User");
+const profile = await userService.getProfile();
+```
+
+#### `send`
+
+Send a raw service method call.
+
+```typescript
+async send(
+  serviceName: string,
+  methodName: string,
+  params: unknown[],
+  progress?: ServiceProgress,
+): Promise<unknown>;
+```
+
+#### `addListener`
+
+Add a server-side event listener.
+
+```typescript
+async addListener<TInfo, TData>(
+  eventDef: ServiceEventDef<TInfo, TData>,
+  info: TInfo,
+  cb: (data: TData) => PromiseLike<void>,
+): Promise<string>;
+```
+
+Returns a listener key (UUID) that can be used with `removeListener`.
+
+#### `removeListener`
+
+Remove a server-side event listener.
+
+```typescript
+async removeListener(key: string): Promise<void>;
+```
+
+#### `emitEvent`
+
+Emit an event to matching server-side listeners.
+
+```typescript
+async emitEvent<TInfo, TData>(
+  eventDef: ServiceEventDef<TInfo, TData>,
+  infoSelector: (item: TInfo) => boolean,
+  data: TData,
+): Promise<void>;
+```
+
+#### `uploadFile`
+
+Upload files to the server. Requires prior authentication via `auth()`.
+
+```typescript
+async uploadFile(
+  files: File[] | FileList | { name: string; data: BlobPart }[],
+): Promise<ServiceUploadResult[]>;
+```
+
+#### `downloadFileBuffer`
+
+Download a file from the server as bytes.
+
+```typescript
+async downloadFileBuffer(relPath: string): Promise<Bytes>;
+```
+
+## `createServiceClient`
+
+Factory function.
+
+```typescript
+function createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient;
+```
+
+## Example
+
+```typescript
+import { createServiceClient, type ServiceProxy } from "@simplysm/service-client";
+import { defineEvent } from "@simplysm/service-common";
+
+// Define event
+const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
+
+// Create client
+const client = createServiceClient("my-app", {
+  host: "localhost",
+  port: 3000,
+});
+
+// Connect and authenticate
+await client.connect();
+await client.auth(jwtToken);
+
+// Call service
+const orderService = client.getService<OrderServiceType>("Order");
+const orders = await orderService.getAll();
+
+// Listen for events
+const key = await client.addListener(OrderUpdated, { orderId: 123 }, async (data) => {
+  console.log(data.status);
+});
+
+// Track progress
+client.on("request-progress", (state) => {
+  console.log(`Upload: ${state.completedSize}/${state.totalSize}`);
+});
+
+// Cleanup
+await client.removeListener(key);
+await client.close();
+```

package/docs/transport.md

@@ -0,0 +1,102 @@
+# Transport
+
+The transport layer handles WebSocket connections and message routing.
+
+## SocketProvider
+
+Low-level WebSocket connection manager with automatic reconnection and heartbeat keep-alive.
+
+### `SocketProviderEvents`
+
+```typescript
+interface SocketProviderEvents {
+  message: Bytes;
+  state: "connected" | "closed" | "reconnecting";
+}
+```
+
+### `SocketProvider`
+
+```typescript
+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>;
+}
+```
+
+### `createSocketProvider`
+
+Create a SocketProvider instance.
+
+```typescript
+function createSocketProvider(
+  url: string,
+  clientName: string,
+  maxReconnectCount: number,
+): SocketProvider;
+```
+
+**Behavior:**
+- Heartbeat: sends ping every 5s, considers disconnected if no message for 30s
+- Reconnect: retries every 3s up to `maxReconnectCount` times
+- Binary protocol: uses `ArrayBuffer` for data transfer
+- Ping/Pong: `0x01` = ping, `0x02` = pong
+
+---
+
+## ServiceTransport
+
+Higher-level transport that handles message encoding/decoding, request-response correlation, and event dispatching.
+
+### `ServiceTransportEvents`
+
+```typescript
+interface ServiceTransportEvents {
+  reload: Set<string>;
+  event: { keys: string[]; data: unknown };
+}
+```
+
+### `ServiceTransport`
+
+```typescript
+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>;
+}
+```
+
+### `createServiceTransport`
+
+Create a ServiceTransport instance.
+
+```typescript
+function createServiceTransport(
+  socket: SocketProvider,
+  protocol: ClientProtocolWrapper,
+): ServiceTransport;
+```
+
+**Behavior:**
+- Each `send()` call generates a unique UUID and registers a pending request
+- Incoming messages are correlated by UUID and resolved/rejected accordingly
+- Progress callbacks are invoked for chunked message transfers
+- All pending requests are rejected when the socket disconnects

package/docs/types.md

@@ -0,0 +1,38 @@
+# Types
+
+## ServiceConnectionOptions
+
+WebSocket connection configuration.
+
+```typescript
+interface ServiceConnectionOptions {
+  port: number;
+  host: string;
+  ssl?: boolean;
+  /** Set to 0 to disable reconnect; disconnects immediately */
+  maxReconnectCount?: number;
+}
+```
+
+## ServiceProgress
+
+Progress callback interface for tracking request/response transfer progress.
+
+```typescript
+interface ServiceProgress {
+  request?: (s: ServiceProgressState) => void;
+  response?: (s: ServiceProgressState) => void;
+}
+```
+
+## ServiceProgressState
+
+Transfer progress state.
+
+```typescript
+interface ServiceProgressState {
+  uuid: string;
+  totalSize: number;
+  completedSize: number;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-client",
-  "version": "13.0.96",
+  "version": "13.0.98",
   "description": "Simplysm package - Service module (client)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -20,9 +20,9 @@
   "sideEffects": false,
   "dependencies": {
     "consola": "^3.4.2",
-    "@simplysm/core-common": "13.0.96",
-    "@simplysm/orm-common": "13.0.96",
-    "@simplysm/service-common": "13.0.96"
+    "@simplysm/core-common": "13.0.98",
+    "@simplysm/orm-common": "13.0.98",
+    "@simplysm/service-common": "13.0.98"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",