@awesome-message/sdk/README.md

Awesome Message SDK for admin, messaging, and notification services

# Awesome Message SDK

<div align="center">
  <!-- <img src="https://via.placeholder.com/200x100?text=AwesomeMessage+SDK" alt="AwesomeMessage SDK 로고" width="200" /> -->
  
  [![npm version](https://img.shields.io/npm/v/@awesome-message/sdk.svg)](https://www.npmjs.com/package/@awesome-message/sdk)
  ![License](https://img.shields.io/badge/license-UNLICENSED-red)
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-blue.svg)](https://www.typescriptlang.org/)
  [![Node.js](https://img.shields.io/badge/Node.js-16.8+-green.svg)](https://nodejs.org/)
</div>

Node.js 환경에서 Awesome Message 서비스와 통합할 수 있는 TypeScript/JavaScript SDK입니다.

## 목차

- [지원 환경](#지원-환경)
- [설치](#설치)
- [주요 기능](#주요-기능)
- [클라이언트 목록](#클라이언트-목록)
- [빠른 시작](#빠른-시작)
- [에러 핸들링](#에러-핸들링)
- [브라우저에서 사용하려면?](#브라우저에서-사용하려면)
- [주의사항](#주의사항)

## 지원 환경

- ✅ Node.js 16.8.0 이상
- ✅ TypeScript 5.8+ 지원
- ❌ 브라우저 환경 미지원 (보안상 이유로 서버 사이드 전용)

## 설치

```bash
npm install @awesome-message/sdk
# 또는
yarn add @awesome-message/sdk
# 또는
pnpm add @awesome-message/sdk
```

## 주요 기능

- **관리자 기능**: 클라이언트 생성 및 관리
- **카카오 비즈니스 메시지**:
  - 카카오 비즈니스 채널 관리 (등록, 인증, 조회, 삭제)
  - 친구톡 이미지 업로드 및 관리
  - 친구톡 템플릿 메시지 (생성, 수정, 삭제, 발송)
  - 친구톡 자유형 메시지 발송 (텍스트, 이미지, 와이드, 커머스 등)
  - 친구톡 메시지 발송 결과 조회
- **카카오 알림톡**:
  - 알림톡 일반/인증 메시지 발송
  - 알림톡 템플릿 관리 (등록, 수정, 조회, 삭제)
  - 알림톡 발송 실패 시 SMS Failback 설정
- **Push 알림**:
  - FCM/APNs 토큰 관리
  - UID/태그 기반 타겟팅 발송
  - 예약/반복 발송 스케줄 관리
  - 발송 통계/분석
- **SMS**:
  - SMS/LMS/MMS 메시지 발송
  - 템플릿 관리
  - 태그 기반 타겟팅
  - 첨부파일 관리
  - 발신번호 관리
- **향후 지원 예정**:
  - 이메일

## 클라이언트 목록

| 클라이언트                       | 설명                              | 문서                                                                                        |
| -------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------- |
| `AdminClient`                    | 클라이언트 생성 및 관리           | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/AdminClient.html)                    |
| `KakaoChannelClient`             | 카카오 비즈니스 채널 관리         | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/KakaoChannelClient.html)             |
| `KakaoFriendtalkImageClient`     | 친구톡 이미지 업로드 및 관리      | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/KakaoFriendtalkImageClient.html)     |
| `KakaoFriendtalkTemplateClient`  | 친구톡 템플릿 메시지 관리 및 발송 | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/KakaoFriendtalkTemplateClient.html)  |
| `KakaoFriendtalkFreestyleClient` | 친구톡 자유형 메시지 발송         | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/KakaoFriendtalkFreestyleClient.html) |
| `KakaoFriendtalkResultClient`    | 친구톡 메시지 발송 결과 조회      | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/KakaoFriendtalkResultClient.html)    |
| `KakaoAlimtalkMessageClient`     | 알림톡 메시지 발송 및 결과 조회   | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/KakaoAlimtalkMessageClient.html)     |
| `KakaoAlimtalkTemplateClient`    | 알림톡 템플릿 관리                | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/KakaoAlimtalkTemplateClient.html)    |
| `KakaoAlimtalkFailbackClient`    | 알림톡 SMS Failback 설정          | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/KakaoAlimtalkFailbackClient.html)    |
| `PushTokenClient`                | Push 토큰 관리                    | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/PushTokenClient.html)                |
| `PushMessageClient`              | Push 메시지 발송                  | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/PushMessageClient.html)              |
| `PushReservationClient`          | Push 예약/반복 발송               | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/PushReservationClient.html)          |
| `PushTagClient`                  | Push 태그 관리                    | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/PushTagClient.html)                  |
| `PushStatsClient`                | Push 통계 조회                    | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/PushStatsClient.html)                |
| `PushUidClient`                  | Push UID 관리                     | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/PushUidClient.html)                  |
| `SmsClient`                      | SMS/LMS/MMS 메시지 발송           | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/SmsClient.html)                      |
| `SmsTemplateClient`              | SMS 템플릿 관리                   | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/SmsTemplateClient.html)              |
| `SmsTagClient`                   | SMS 태그 관리                     | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/SmsTagClient.html)                   |
| `SmsAttachmentClient`            | SMS 첨부파일 관리                 | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/SmsAttachmentClient.html)            |
| `SmsManagementClient`            | SMS 발신번호 관리                 | [📖 문서](https://d9j1chazr0yni.cloudfront.net/classes/SmsManagementClient.html)            |

## 빠른 시작

### 1. 클라이언트 생성

```typescript
import { AdminClient } from "@awesome-message/sdk";

const adminClient = new AdminClient({
  accessKeyId: process.env.ACCESS_KEY_ID!,
  secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

// externalId는 기존에 사용하던 고유 식별자를 사용합니다
// (브랜드, 사이트, 클라이언트, 프로젝트 단위 등 자유롭게 설정 가능)
const client = await adminClient.createClient({
  externalId: "my-ecommerce-site",
  name: "이커머스 사이트",
});

console.log("클라이언트 생성 완료:", client);
```

### 2. 카카오 채널 등록 및 인증

```typescript
import { KakaoChannelClient } from "@awesome-message/sdk";

const kakaoChannelClient = new KakaoChannelClient({
  accessKeyId: process.env.ACCESS_KEY_ID!,
  secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

// 1. 채널 등록
const channel = await kakaoChannelClient.createChannel("my-ecommerce-site", {
  plusFriendId: "@mycompany",
  phoneNo: "01500000000",
  categoryCode: "01800010001", // 카테고리는 getChannelCategories()로 조회 가능
});

// 2. 카카오톡 앱에서 받은 토큰으로 인증
const authenticatedChannel = await kakaoChannelClient.authenticateChannelToken(
  "my-ecommerce-site",
  {
    plusFriendId: "@mycompany",
    token: 123456, // 카카오톡 앱에서 받은 6자리 숫자
  }
);

console.log("인증 완료된 채널:", authenticatedChannel);
```

### 3. 친구톡 메시지 발송

```typescript
import { KakaoFriendtalkFreestyleClient } from "@awesome-message/sdk";

const friendtalkClient = new KakaoFriendtalkFreestyleClient({
  accessKeyId: process.env.ACCESS_KEY_ID!,
  secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

// 자유형 텍스트 메시지 발송
const result = await friendtalkClient.sendFriendtalkTextMessage(
  "my-ecommerce-site",
  {
    senderKey: "209880bcc4817fc57ba1d5ce69d863d379a1c881", // 채널 인증 후 받은 발신키
    content: "안녕하세요! 새로운 할인 이벤트를 시작합니다.",
    recipientList: [
      { recipientNo: "01234567890" },
      { recipientNo: "01987654321" },
    ],
    buttons: [
      {
        name: "이벤트 보기",
        type: "WL",
        linkMo: "https://example.com/event",
      },
    ],
  }
);

console.log("메시지 발송 결과:", result);
```

## 에러 핸들링

SDK는 HTTP 상태 코드에 따라 자동으로 적절한 예외 클래스로 변환합니다:

```typescript
import {
  InvalidParameterException,
  AccessDeniedException,
  NotFoundException,
  InternalServerErrorException,
} from "@awesome-message/sdk";

try {
  const result = await adminClient.createClient({
    externalId: "my-client",
    name: "테스트 클라이언트",
  });
} catch (error) {
  if (error instanceof InvalidParameterException) {
    console.error("잘못된 요청 파라미터:", error.message);
  } else if (error instanceof AccessDeniedException) {
    console.error("권한 없음:", error.message);
  } else if (error instanceof NotFoundException) {
    console.error("리소스를 찾을 수 없음:", error.message);
  } else if (error instanceof InternalServerErrorException) {
    console.error("서버 내부 오류:", error.message);
  } else {
    console.error("알 수 없는 오류:", error);
  }
}
```

## 브라우저에서 사용하려면?

보안상의 이유로 브라우저에서는 직접 SDK를 사용할 수 없습니다. 대신 다음과 같은 방식을 권장합니다:

### Next.js API Routes 예시

```typescript
// pages/api/send-message.ts 또는 app/api/send-message/route.ts
import { KakaoFriendtalkFreestyleClient } from "@awesome-message/sdk";

const friendtalkClient = new KakaoFriendtalkFreestyleClient({
  accessKeyId: process.env.ACCESS_KEY_ID!,
  secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

export async function POST(request: Request) {
  try {
    const { recipients, message } = await request.json();

    const result = await friendtalkClient.sendFriendtalkTextMessage(
      "my-client",
      {
        senderKey: process.env.KAKAO_SENDER_KEY!,
        content: message,
        recipientList: recipients,
      }
    );

    return Response.json({ success: true, result });
  } catch (error) {
    return Response.json(
      { success: false, error: error.message },
      { status: 500 }
    );
  }
}
```

### Express.js 예시

```typescript
import express from "express";
import { KakaoFriendtalkFreestyleClient } from "@awesome-message/sdk";

const app = express();
const friendtalkClient = new KakaoFriendtalkFreestyleClient({
  accessKeyId: process.env.ACCESS_KEY_ID!,
  secretAccessKey: process.env.SECRET_ACCESS_KEY!,
});

app.post("/api/send-message", async (req, res) => {
  try {
    const { recipients, message } = req.body;

    const result = await friendtalkClient.sendFriendtalkTextMessage(
      "my-client",
      {
        senderKey: process.env.KAKAO_SENDER_KEY!,
        content: message,
        recipientList: recipients,
      }
    );

    res.json({ success: true, result });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});
```

## 주의사항

- 🔑 **보안**: 액세스 키와 시크릿 키는 환경변수로 관리하고 절대 클라이언트 사이드에 노출하지 마세요
- 🔄 **비동기 처리**: 모든 API 호출은 비동기(async/await)로 처리됩니다
- 🖥️ **서버 전용**: Node.js 환경에서만 실행됩니다 (브라우저 사용 불가)
- 📋 **타입 안정성**: TypeScript를 사용하면 컴파일 타임에 타입 검사를 받을 수 있습니다
- 🏷️ **externalId**: 클라이언트 식별을 위한 externalId는 일관성 있게 사용하세요