@simplysm/storage 14.0.48 → 14.0.50

package/README.md

@@ -12,171 +12,24 @@ npm install @simplysm/storage
 
 ### Types
 
-| API | Type | Description |
-|-----|------|-------------|
-| `StorageProtocol` | type | 지원 프로토콜 유니온 타입 (`"ftp"` \| `"ftps"` \| `"sftp"`) |
-| `StorageConnConfig` | interface | 스토리지 연결 설정 |
-| `FileInfo` | interface | 파일/디렉토리 정보 |
-| `StorageClient` | interface | 스토리지 클라이언트 공통 인터페이스 |
-
-#### `StorageProtocol`
-
-```typescript
-type StorageProtocol = "ftp" | "ftps" | "sftp";
-```
-
-지원하는 프로토콜을 나타내는 유니온 타입:
-- `"ftp"`: 일반 FTP 프로토콜
-- `"ftps"`: TLS/SSL 암호화 FTP 프로토콜
-- `"sftp"`: SSH 기반 SFTP 프로토콜
-
-#### `StorageConnConfig`
-
-```typescript
-interface StorageConnConfig {
-  host: string;
-  port?: number;
-  user?: string;
-  password?: string;
-}
-```
-
-| Field | Type | Description |
+| Entry | Kind | Description |
 |-------|------|-------------|
-| `host` | `string` | 서버 호스트 주소 |
-| `port` | `number \| undefined` | 포트 번호. 생략 시 프로토콜 기본값 사용 (FTP: 21, FTPS: 21, SFTP: 22) |
-| `user` | `string \| undefined` | 사용자 이름 |
-| `password` | `string \| undefined` | 비밀번호. SFTP에서 생략하면 SSH agent (`SSH_AUTH_SOCK` 환경변수) + `~/.ssh/id_ed25519` 키 파일 인증을 순서대로 시도 |
-
-#### `FileInfo`
-
-```typescript
-interface FileInfo {
-  name: string;
-  isFile: boolean;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | 파일 또는 디렉토리의 이름 |
-| `isFile` | `boolean` | `true`이면 파일, `false`이면 디렉토리 |
-
-#### `StorageClient`
-
-스토리지 클라이언트 공통 인터페이스. `FtpStorageClient`와 `SftpStorageClient`가 구현한다.
-
-```typescript
-interface StorageClient {
-  connect(config: StorageConnConfig): Promise<void>;
-  mkdir(dirPath: string): Promise<void>;
-  rename(fromPath: string, toPath: string): Promise<void>;
-  list(dirPath: string): Promise<FileInfo[]>;
-  readFile(filePath: string): Promise<Bytes>;
-  exists(filePath: string): Promise<boolean>;
-  put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
-  uploadDir(fromPath: string, toPath: string): Promise<void>;
-  remove(filePath: string): Promise<void>;
-  close(): Promise<void>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `connect` | `config: StorageConnConfig` | `Promise<void>` | 스토리지 서버에 연결. 연결 해제 전 한 번만 호출 가능 |
-| `mkdir` | `dirPath: string` | `Promise<void>` | 디렉토리 생성. 부모 디렉토리가 없으면 함께 생성 |
-| `rename` | `fromPath: string, toPath: string` | `Promise<void>` | 파일/디렉토리 이름 변경 또는 이동 |
-| `list` | `dirPath: string` | `Promise<FileInfo[]>` | 디렉토리 내 파일/디렉토리 목록 조회 |
-| `readFile` | `filePath: string` | `Promise<Bytes>` | 파일 내용을 `Bytes`(`Uint8Array`)로 읽기 |
-| `exists` | `filePath: string` | `Promise<boolean>` | 파일/디렉토리 존재 여부 확인. 모든 예외는 `false` 반환 |
-| `put` | `localPathOrBuffer: string \| Bytes, storageFilePath: string` | `Promise<void>` | 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드 |
-| `uploadDir` | `fromPath: string, toPath: string` | `Promise<void>` | 로컬 디렉토리 전체를 원격 경로에 업로드 |
-| `remove` | `filePath: string` | `Promise<void>` | 파일 삭제 |
-| `close` | 없음 | `Promise<void>` | 연결 종료. 이미 종료된 상태에서 호출해도 안전 |
+| [`StorageConnConfig`](./docs/types/storage-conn-config.md) | interface | 스토리지 서버 연결 설정 |
+| [`FileInfo`](./docs/types/file-info.md) | interface | 파일/디렉토리 정보 |
+| [`StorageClient`](./docs/types/storage-client.md) | interface | 스토리지 클라이언트 공통 인터페이스 (포함: `StorageProtocol`) |
 
 ### Clients
 
-| API | Type | Description |
-|-----|------|-------------|
-| `FtpStorageClient` | class | FTP/FTPS 프로토콜 스토리지 클라이언트 (`basic-ftp` 라이브러리 기반) |
-| `SftpStorageClient` | class | SFTP 프로토콜 스토리지 클라이언트 (`ssh2-sftp-client` 라이브러리 기반) |
-
-#### `FtpStorageClient`
-
-FTP/FTPS 프로토콜을 사용하는 스토리지 클라이언트. `StorageClient` 인터페이스를 구현한다.
-
-```typescript
-class FtpStorageClient implements StorageClient {
-  constructor(private readonly _secure: boolean = false);
-}
-```
-
-**생성자**:
-- `_secure`: `true`이면 FTPS (TLS/SSL 암호화), `false`이면 FTP (기본값)
-
-**특징**:
-- `connect()`로 연결 후 메서드 호출. 미연결 상태에서 호출하면 `SdError` 발생
-- `exists()`는 먼저 `size()` 명령으로 파일을 O(1) 성능으로 확인하고, 실패 시 부모 디렉토리 목록을 조회하여 디렉토리 존재 여부 확인. 모든 예외는 `false` 반환
-- 슬래시가 없는 경로(예: `file.txt`)는 루트 디렉토리(`/`)에서 검색
-- `close()`는 이미 종료된 상태에서 호출해도 안전 (오류 미발생)
-
-#### `SftpStorageClient`
-
-SFTP 프로토콜을 사용하는 스토리지 클라이언트. `StorageClient` 인터페이스를 구현한다.
-
-```typescript
-class SftpStorageClient implements StorageClient {
-  constructor();
-}
-```
-
-**인증 메커니즘**:
-- `password`가 있으면 패스워드 인증 사용
-- `password`가 없으면 다음 순서대로 시도:
-  1. SSH agent (`SSH_AUTH_SOCK` 환경변수 설정 시)
-  2. `~/.ssh/id_ed25519` 개인키 파일 인증
-  3. privateKey 파싱 실패 시 (암호화된 키 등) agent만으로 재시도
-
-**특징**:
-- `connect()`로 연결 후 메서드 호출. 미연결 상태에서 호출하면 `SdError` 발생
-- `exists()`는 `ssh2-sftp-client`의 `exists()` 반환값 (`false | 'd' | '-' | 'l'`)을 검사하여 존재 여부 판단. 모든 예외는 `false` 반환
-- `close()`는 이미 종료된 상태에서 호출해도 안전 (오류 미발생)
+| Entry | Kind | Description |
+|-------|------|-------------|
+| [`FtpStorageClient`](./docs/clients/ftp-storage-client.md) | class | FTP/FTPS 프로토콜 스토리지 클라이언트 (`basic-ftp` 기반) |
+| [`SftpStorageClient`](./docs/clients/sftp-storage-client.md) | class | SFTP 프로토콜 스토리지 클라이언트 (`ssh2-sftp-client` 기반) |
 
 ### Factory
 
-| API | Type | Description |
-|-----|------|-------------|
-| `StorageFactory` | class | 프로토콜별 클라이언트 생성 및 연결 생명주기 자동 관리 |
-
-#### `StorageFactory`
-
-스토리지 클라이언트 팩토리. 콜백 패턴으로 연결/종료를 자동 관리한다.
-
-```typescript
-class StorageFactory {
-  static async connect<R>(
-    type: StorageProtocol,
-    config: StorageConnConfig,
-    fn: (storage: StorageClient) => R | Promise<R>,
-  ): Promise<R>;
-}
-```
-
-**메서드**:
-- `StorageFactory.connect<R>()` (정적 메서드)
-
-**파라미터**:
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `type` | `StorageProtocol` | 프로토콜 타입 (`"ftp"`, `"ftps"`, `"sftp"`) |
-| `config` | `StorageConnConfig` | 연결 설정 |
-| `fn` | `(storage: StorageClient) => R \| Promise<R>` | 연결된 클라이언트를 받아 작업을 수행하는 콜백. 반환값은 `Promise<R>` 형태로 래핑되어 반환됨 |
-
-**동작**:
-- `fn` 콜백이 완료되거나 예외를 발생시키면 연결이 자동으로 종료됨
-- `fn`에서 발생한 예외는 그대로 전파됨
-- 반환값: 콜백의 반환값
+| Entry | Kind | Description |
+|-------|------|-------------|
+| [`StorageFactory`](./docs/factory/storage-factory.md) | class | 프로토콜별 클라이언트 생성 및 연결 생명주기 자동 관리 (포함: `StorageProtocol`) |
 
 ## Usage Examples
 
@@ -210,92 +63,22 @@ const files = await StorageFactory.connect(
     for (const file of list.filter((f) => f.isFile)) {
       const content = await storage.readFile(`/data/${file.name}`);
       // content는 Bytes (Uint8Array)
-      console.log(`Read ${file.name}: ${content.length} bytes`);
     }
     return list;
   },
 );
 ```
 
-### FTPS로 파일 이름 변경
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-await StorageFactory.connect(
-  "ftps",
-  { host: "ftps.example.com", user: "user", password: "pass" },
-  async (storage) => {
-    const exists = await storage.exists("/remote/file.txt");
-    if (exists) {
-      await storage.rename("/remote/file.txt", "/remote/backup.txt");
-    }
-  },
-);
-```
-
-### 클라이언트 직접 사용 (수동 생명주기 관리)
-
-클라이언트를 직접 인스턴스화하여 수동으로 연결 생명주기를 관리할 수 있다. 하지만 연결 누수 위험이 있으므로 `StorageFactory.connect` 사용을 권장한다.
-
-```typescript
-import { FtpStorageClient } from "@simplysm/storage";
-
-const client = new FtpStorageClient(true); // FTPS 사용
-try {
-  await client.connect({ host: "ftps.example.com", user: "user", password: "pass" });
-  const exists = await client.exists("/remote/file.txt");
-  if (exists) {
-    await client.rename("/remote/file.txt", "/remote/backup.txt");
-  }
-} finally {
-  await client.close();
-}
-```
-
 ### SSH 키 인증으로 SFTP 연결 (비밀번호 생략)
 
-`password`를 생략하면 SSH agent와 `~/.ssh/id_ed25519` 키 파일을 사용하여 인증한다.
-
 ```typescript
 import { StorageFactory } from "@simplysm/storage";
 
 await StorageFactory.connect(
   "sftp",
-  { host: "sftp.example.com", user: "user" }, // password 생략
+  { host: "sftp.example.com", user: "user" }, // password 생략 → SSH agent/키 파일 인증
   async (storage) => {
     const list = await storage.list("/home/user");
-    console.log(`Files: ${list.map((f) => f.name).join(", ")}`);
-  },
-);
-```
-
-### 바이트 데이터로 파일 업로드
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
-
-await StorageFactory.connect(
-  "sftp",
-  { host: "sftp.example.com", user: "user", password: "pass" },
-  async (storage) => {
-    await storage.put(data, "/remote/file.bin");
-  },
-);
-```
-
-### 로컬 디렉토리 전체 업로드
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-await StorageFactory.connect(
-  "ftp",
-  { host: "ftp.example.com", user: "user", password: "pass" },
-  async (storage) => {
-    await storage.uploadDir("/local/folder", "/remote/backup");
   },
 );
 ```

package/docs/clients/ftp-storage-client.md

@@ -0,0 +1,47 @@
+# FtpStorageClient
+
+FTP/FTPS 프로토콜을 사용하는 스토리지 클라이언트. `basic-ftp` 라이브러리 기반. [`StorageClient`](../types/storage-client.md) 인터페이스를 구현한다.
+
+직접 사용하기보다 [`StorageFactory.connect()`](../factory/storage-factory.md)를 통해 콜백 패턴으로 사용하는 것을 권장한다.
+
+```typescript
+class FtpStorageClient implements StorageClient {
+  constructor(private readonly _secure: boolean = false);
+}
+```
+
+## Constructor
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `_secure` | `boolean` | `false` | `true`이면 FTPS (TLS/SSL 암호화), `false`이면 FTP |
+
+## Members
+
+[`StorageClient`](../types/storage-client.md) 인터페이스의 모든 메서드를 구현한다. 구현 특이사항:
+
+| Member | Kind | Description |
+|--------|------|-------------|
+| `connect` | method | 이미 연결된 상태에서 호출하면 `SdError` 발생. 연결 실패 시 내부 `ftp.Client`를 즉시 닫고 예외를 전파 |
+| `mkdir` | method | `basic-ftp`의 `ensureDir()`을 사용하여 부모 디렉토리 포함 재귀 생성 |
+| `exists` | method | 먼저 `size()` 명령으로 파일을 O(1) 성능으로 확인. 실패 시 부모 디렉토리 `list()`로 디렉토리 존재 여부 확인. 슬래시 없는 경로(예: `file.txt`)는 루트(`/`)에서 검색. 모든 예외는 `false` 반환 |
+| `put` | method | `string`이면 파일 경로로, `Bytes`이면 `Readable` 스트림으로 변환하여 `uploadFrom()` 호출 |
+| `close` | method | 동기적으로 내부 클라이언트를 정리하고 `Promise.resolve()` 반환. 이미 종료된 상태에서 호출해도 안전 |
+
+## Usage
+
+```typescript
+import { FtpStorageClient } from "@simplysm/storage";
+
+// FTPS 사용
+const client = new FtpStorageClient(true);
+try {
+  await client.connect({ host: "ftps.example.com", user: "user", password: "pass" });
+  const exists = await client.exists("/remote/file.txt");
+  if (exists) {
+    await client.rename("/remote/file.txt", "/remote/backup.txt");
+  }
+} finally {
+  await client.close();
+}
+```

package/docs/clients/sftp-storage-client.md

@@ -0,0 +1,58 @@
+# SftpStorageClient
+
+SFTP 프로토콜을 사용하는 스토리지 클라이언트. `ssh2-sftp-client` 라이브러리 기반. [`StorageClient`](../types/storage-client.md) 인터페이스를 구현한다.
+
+직접 사용하기보다 [`StorageFactory.connect()`](../factory/storage-factory.md)를 통해 콜백 패턴으로 사용하는 것을 권장한다.
+
+```typescript
+class SftpStorageClient implements StorageClient {
+  constructor();
+}
+```
+
+## Members
+
+[`StorageClient`](../types/storage-client.md) 인터페이스의 모든 메서드를 구현한다. 구현 특이사항:
+
+| Member | Kind | Description |
+|--------|------|-------------|
+| `connect` | method | 이미 연결된 상태에서 호출하면 `SdError` 발생. `password` 유무에 따라 인증 방식이 달라짐 (아래 인증 메커니즘 참조). 연결 실패 시 `client.end()`를 호출하고 예외를 전파 |
+| `mkdir` | method | `ssh2-sftp-client`의 `mkdir(path, true)`를 호출하여 부모 디렉토리 포함 재귀 생성 |
+| `list` | method | `item.type === "-"`이면 파일(`isFile: true`), 아니면 디렉토리(`isFile: false`)로 변환 |
+| `exists` | method | `ssh2-sftp-client`의 `exists()` 반환값(`false \| 'd' \| '-' \| 'l'`)을 검사. 문자열이면 존재. 모든 예외는 `false` 반환 |
+| `readFile` | method | `ssh2-sftp-client`의 `get()` 반환값(`Buffer` 또는 `string`)을 `Bytes`(`Uint8Array`)로 변환 |
+| `put` | method | `string`이면 `fastPut()`으로, `Bytes`이면 `Buffer.from()` 변환 후 `put()`으로 업로드 (`ssh2-sftp-client` 라이브러리 요구사항) |
+| `close` | method | `client.end()`를 호출하여 연결 종료. 이미 종료된 상태에서 호출해도 안전 |
+
+## Authentication
+
+`connect()` 호출 시 [`StorageConnConfig`](../types/storage-conn-config.md)의 `password` 유무에 따라 인증 방식이 결정된다:
+
+**`password`가 있는 경우**: 패스워드 인증
+
+**`password`가 없는 경우**: 다음 순서로 시도
+1. SSH agent (`SSH_AUTH_SOCK` 환경변수가 설정된 경우 `agent` 옵션 추가)
+2. `~/.ssh/id_ed25519` 개인키 파일 읽어 `privateKey` 옵션으로 인증 시도
+3. `privateKey` 파싱 실패 시 (암호화된 키 등) SSH agent만으로 재시도
+
+## Usage
+
+```typescript
+import { SftpStorageClient } from "@simplysm/storage";
+
+// 패스워드 인증
+const client = new SftpStorageClient();
+try {
+  await client.connect({ host: "sftp.example.com", user: "user", password: "pass" });
+  await client.mkdir("/remote/dir");
+  await client.put("/local/file.txt", "/remote/dir/file.txt");
+} finally {
+  await client.close();
+}
+```
+
+SSH 키 인증 사용 시 `password` 필드를 생략한다:
+
+```typescript
+await client.connect({ host: "sftp.example.com", user: "user" }); // password 생략
+```

package/docs/factory/storage-factory.md

@@ -0,0 +1,82 @@
+# StorageFactory
+
+스토리지 클라이언트 팩토리. 콜백 패턴으로 연결/종료를 자동 관리한다.
+
+```typescript
+class StorageFactory {
+  static async connect<R>(
+    type: StorageProtocol,
+    config: StorageConnConfig,
+    fn: (storage: StorageClient) => R | Promise<R>,
+  ): Promise<R>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connect` | static | `<R>(type: StorageProtocol, config: StorageConnConfig, fn: (storage: StorageClient) => R \| Promise<R>) => Promise<R>` | 프로토콜에 맞는 클라이언트를 생성하고, 연결 후 콜백을 실행하며, 완료/예외 시 자동으로 연결을 종료 |
+
+### `connect<R>()` 파라미터
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | `StorageProtocol` | 프로토콜 타입 |
+| `config` | [`StorageConnConfig`](../types/storage-conn-config.md) | 연결 설정 |
+| `fn` | `(storage: StorageClient) => R \| Promise<R>` | 연결된 클라이언트로 작업을 수행하는 콜백 |
+
+**반환**: `Promise<R>` — 콜백의 반환값
+
+**동작**:
+- `type`에 따라 [`FtpStorageClient`](../clients/ftp-storage-client.md) 또는 [`SftpStorageClient`](../clients/sftp-storage-client.md)를 생성
+- `client.connect(config)` 후 `fn(client)` 실행
+- `fn` 완료 또는 예외 발생 여부와 무관하게 `finally`에서 `client.close()` 호출
+- `fn`에서 발생한 예외는 그대로 전파
+
+## Related Types
+
+### `StorageProtocol`
+
+`StorageFactory.connect()`의 `type` 파라미터 타입.
+
+```typescript
+type StorageProtocol = "ftp" | "ftps" | "sftp";
+```
+
+| Variant | Description |
+|---------|-------------|
+| `"ftp"` | 일반 FTP. `FtpStorageClient(false)` 생성 |
+| `"ftps"` | TLS/SSL 암호화 FTP. `FtpStorageClient(true)` 생성 |
+| `"sftp"` | SSH 기반 SFTP. `SftpStorageClient()` 생성 |
+
+## Usage
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+// 파일 업로드
+await StorageFactory.connect(
+  "sftp",
+  { host: "sftp.example.com", user: "user", password: "pass" },
+  async (storage) => {
+    await storage.mkdir("/remote/dir");
+    await storage.put("/local/file.txt", "/remote/dir/file.txt");
+  },
+);
+
+// 파일 목록 조회 후 반환
+const list = await StorageFactory.connect(
+  "ftp",
+  { host: "ftp.example.com", port: 21, user: "user", password: "pass" },
+  (storage) => storage.list("/data"),
+);
+
+// 바이트 데이터로 업로드
+const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
+await StorageFactory.connect(
+  "ftps",
+  { host: "ftps.example.com", user: "user", password: "pass" },
+  (storage) => storage.put(data, "/remote/file.bin"),
+);
+```

package/docs/types/file-info.md

@@ -0,0 +1,32 @@
+# FileInfo
+
+파일 또는 디렉토리 정보를 담는 인터페이스. [`StorageClient.list()`](./storage-client.md)의 반환 타입이다.
+
+```typescript
+interface FileInfo {
+  name: string;
+  isFile: boolean;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | 파일 또는 디렉토리의 이름 (경로 아님, 이름만) |
+| `isFile` | `boolean` | `true`이면 파일, `false`이면 디렉토리 |
+
+## Usage
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+const items = await StorageFactory.connect(
+  "sftp",
+  { host: "sftp.example.com", user: "user", password: "pass" },
+  async (storage) => storage.list("/remote/dir"),
+);
+
+const files = items.filter((item) => item.isFile);
+const dirs = items.filter((item) => !item.isFile);
+```

package/docs/types/storage-client.md

@@ -0,0 +1,50 @@
+# StorageClient
+
+스토리지 클라이언트 공통 인터페이스. [`FtpStorageClient`](../clients/ftp-storage-client.md)와 [`SftpStorageClient`](../clients/sftp-storage-client.md)가 구현한다.
+
+직접 사용하기보다 [`StorageFactory.connect()`](../factory/storage-factory.md)를 통해 콜백 패턴으로 사용하는 것을 권장한다.
+
+```typescript
+interface StorageClient {
+  connect(config: StorageConnConfig): Promise<void>;
+  mkdir(dirPath: string): Promise<void>;
+  rename(fromPath: string, toPath: string): Promise<void>;
+  list(dirPath: string): Promise<FileInfo[]>;
+  readFile(filePath: string): Promise<Bytes>;
+  exists(filePath: string): Promise<boolean>;
+  put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
+  uploadDir(fromPath: string, toPath: string): Promise<void>;
+  remove(filePath: string): Promise<void>;
+  close(): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connect` | method | `(config: StorageConnConfig) => Promise<void>` | 스토리지 서버에 연결. 이미 연결된 상태에서 호출하면 `SdError` 발생 |
+| `mkdir` | method | `(dirPath: string) => Promise<void>` | 디렉토리 생성. 부모 디렉토리가 없으면 함께 생성 |
+| `rename` | method | `(fromPath: string, toPath: string) => Promise<void>` | 파일/디렉토리 이름 변경 또는 이동 |
+| `list` | method | `(dirPath: string) => Promise<FileInfo[]>` | 디렉토리 내 파일/디렉토리 목록 조회 |
+| `readFile` | method | `(filePath: string) => Promise<Bytes>` | 파일 내용을 `Bytes`(`Uint8Array`)로 읽기 |
+| `exists` | method | `(filePath: string) => Promise<boolean>` | 파일/디렉토리 존재 여부 확인. 모든 예외는 `false` 반환 |
+| `put` | method | `(localPathOrBuffer: string \| Bytes, storageFilePath: string) => Promise<void>` | 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드 |
+| `uploadDir` | method | `(fromPath: string, toPath: string) => Promise<void>` | 로컬 디렉토리 전체를 원격 경로에 업로드 |
+| `remove` | method | `(filePath: string) => Promise<void>` | 파일 삭제 |
+| `close` | method | `() => Promise<void>` | 연결 종료. 이미 종료된 상태에서 호출해도 안전 |
+
+## Usage
+
+```typescript
+import type { StorageClient } from "@simplysm/storage";
+import { StorageFactory } from "@simplysm/storage";
+
+// StorageClient 타입을 직접 사용하는 경우 (예: 함수 파라미터 타입)
+async function doWork(storage: StorageClient): Promise<void> {
+  await storage.mkdir("/remote/dir");
+  await storage.put("/local/file.txt", "/remote/dir/file.txt");
+}
+
+await StorageFactory.connect("sftp", { host: "sftp.example.com", user: "user", password: "pass" }, doWork);
+```

package/docs/types/storage-conn-config.md

@@ -0,0 +1,34 @@
+# StorageConnConfig
+
+스토리지 서버 연결 설정 인터페이스.
+
+```typescript
+interface StorageConnConfig {
+  host: string;
+  port?: number;
+  user?: string;
+  password?: string;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `host` | `string` | 서버 호스트 주소 |
+| `port` | `number \| undefined` | 포트 번호. 생략 시 프로토콜 기본값 사용 (FTP/FTPS: 21, SFTP: 22) |
+| `user` | `string \| undefined` | 사용자 이름 |
+| `password` | `string \| undefined` | 비밀번호. SFTP에서 생략하면 SSH agent + `~/.ssh/id_ed25519` 키 파일 인증을 순서대로 시도 |
+
+## Usage
+
+```typescript
+import type { StorageConnConfig } from "@simplysm/storage";
+
+const config: StorageConnConfig = {
+  host: "sftp.example.com",
+  port: 22,
+  user: "user",
+  password: "pass",
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/storage",
-  "version": "14.0.48",
+  "version": "14.0.50",
   "description": "심플리즘 패키지 - 저장소 (node)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,13 +14,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {
     "basic-ftp": "^5.3.0",
     "ssh2-sftp-client": "^12.1.1",
-    "@simplysm/core-common": "14.0.48"
+    "@simplysm/core-common": "14.0.50"
   },
   "devDependencies": {
     "@types/ssh2-sftp-client": "^9.0.6"