npm package: @ohbyeongmun/s3-manager
Description: 재사용 가능한 AWS S3 관리 라이브러리.
Latest version: 1.0.5

# 🪣 @ohbyeongmun/s3-manager

재사용 가능한 AWS S3 관리 라이브러리.  

---

## 🚀 설치

```bash
npm install @ohbyeongmun/s3-manager
# or
yarn add @ohbyeongmun/s3-manager
```

---

## ⚙️ 초기화

환경 변수 대신 코드에서 직접 설정을 주입한다.

```ts
import { initS3 } from "@ohbyeongmun/s3-manager";

initS3({
  accessKeyId: "AKIAXXXXXXX",
  secretAccessKey: "SECRETXXXXXXX",
  region: "ap-northeast-2",
  bucket: "my-app-uploads",
});
```

---

## 🧩 주요 기능

### 1. Presigned URL 발급 (단일 업로드)

```ts
import { S3Service } from "@ohbyeongmun/s3-manager";

const result = await S3Service.getPresignedUploadUrl("profile.png", "avatars");

console.log(result.url);        // 프리사인 업로드 URL
console.log(result.publicUrl);  // 업로드 후 접근 가능한 S3 공개 URL
console.log(result.key);        // S3 Object Key
```

> 프리사인 URL 유효시간은 기본 5분 (300초).  
> 필요 시 라이브러리 내부에서 `expiresIn`을 수정해 커스터마이징 가능.

---

### 2. 🔥 멀티 Presigned URL 발급 (병렬 처리)

여러 파일 이름을 받아 한 번에 Presigned URL을 발급한다.

```ts
const files = ["profile.png", "banner.jpg", "document.pdf"];
const results = await S3Service.getPresignedUploadUrls(files, "multi-test");

results.forEach((r) => {
  console.log(r.url);
});
```

---

### 3. 🔥 멀티 파일 직접 업로드 (버퍼 기반)

```ts
import fs from "fs";
import { S3Service } from "@ohbyeongmun/s3-manager";

const files = [
  { buffer: fs.readFileSync("./1.png"), key: "multi/1.png" },
  { buffer: fs.readFileSync("./2.png"), key: "multi/2.png" },
  { buffer: fs.readFileSync("./3.png"), key: "multi/3.png" },
];

const uploaded = await S3Service.uploadFiles(files);
console.log(uploaded);
```

---

### 4. 🔥 멀티 파일 삭제

```ts
await S3Service.deleteFiles([
  "multi/1.png",
  "multi/2.png",
  "multi/3.png",
]);
```

---

### 5. 단일 파일 삭제

```ts
await S3Service.deleteFile("uploads/2025/11/10/20251110_1123_profile_a2b34cde.png");
```

---

### 6. 다운로드용 Presigned URL

```ts
const downloadUrl = await S3Service.getPresignedDownloadUrl("docs/invoice.pdf");
console.log(downloadUrl);
```

---

### 7. 직접 업로드 (버퍼 기반)

```ts
import fs from "fs";
import { S3Service } from "@ohbyeongmun/s3-manager";

const fileBuffer = fs.readFileSync("./local/image.png");

await S3Service.uploadFile(fileBuffer, "manual_upload/image.png");
```

---

### 8. 파일명 자동 생성 규칙

`generateFileName(originalName, prefix?)`  
예시 결과:

```
uploads/2025/11/10/20251110_1432_프로필_4f2a5cde.png
```

형식:
```
{prefix}/{YYYY}/{MM}/{DD}/{날짜시간}_{원본파일명}_{UUID8}.ext
```

---

## 📦 설정 타입 (S3Config)

```ts
interface S3Config {
  accessKeyId: string;
  secretAccessKey: string;
  region: string;
  bucket: string;
  baseUrl?: string; // CDN 경로 지정 가능
}
```

---

## 💡 예시 통합 (NestJS나 Express 등)

```ts
import { initS3, S3Service } from "@ohbyeongmun/s3-manager";

initS3({
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  region: "ap-northeast-2",
  bucket: "metamonster-uploads",
});

export const uploadHandler = async (req, res) => {
  const presigned = await S3Service.getPresignedUploadUrl(req.body.filename, "uploads");
  res.json(presigned);
};
```

---

## 🧱 의존성

- [@aws-sdk/client-s3](https://www.npmjs.com/package/@aws-sdk/client-s3)
- [@aws-sdk/s3-request-presigner](https://www.npmjs.com/package/@aws-sdk/s3-request-presigner)
- [uuid](https://www.npmjs.com/package/uuid)
- [dayjs](https://day.js.org/)

---

## 🧩 빌드

```bash
npm run build
```

빌드 결과는 `/dist` 폴더에 생성됨.

---

## 🪪 라이선스

MIT License  
Copyright © 2025  
Maintained by [@ohbyeongmun](https://github.com/ohbyeongmun)