npm package: @lumir-company/amaranth-sdk
Description: Amaranth10 API SDK (인증, SSO, 조직도 연동, 통합알림)
Latest version: 0.0.4

# Amaranth10 API SDK

Amaranth10 그룹웨어 API 연동용 TypeScript SDK입니다.  
API 명세는 `api_docs/` 문서를 기준으로 합니다.

## 설치

```bash
npm install amaranth-sdk
```

## 폴더 구조

```
amaranth-sdk/
├── api_docs/           # API 명세 문서
│   ├── 1. guide.md      # 인증 프로토콜 가이드
│   ├── 2. authorization.md
│   ├── 3. sso.md
│   ├── 4. org-integrate.md
│   ├── 5. approval.md
│   └── 6. notification.md
├── src/
│   ├── index.ts         # 진입점 및 export
│   ├── client.ts        # AmaranthClient 클래스
│   ├── common/          # 공통
│   │   ├── constants.ts # API 경로 상수
│   │   ├── types.ts     # 공통 타입
│   │   └── request.ts   # 헤더 생성, apiRequest
│   ├── crypto/          # 암호화
│   │   ├── sign.ts      # wehago-sign (HmacSHA256)
│   │   └── aes.ts       # loginIdEnc / empSeqEnc (AES-128-CBC)
│   ├── auth/            # 인증 토큰 발급 (api99u01A01)
│   ├── sso/             # SSO 공통 + 전자결재 (api99u01A02, authUser)
│   ├── org/             # 조직도 연동 (A03, A04, A05)
│   └── notification/    # 통합알림 (api99u07A01)
├── dist/                # 빌드 결과 (npm run build)
├── package.json
└── tsconfig.build.json
```

## 설치 및 빌드

```bash
npm install
npm run build
```

## e2e 테스트

실제 API를 호출하는 e2e 테스트를 실행하려면 프로젝트 루트에 `.env`를 두고 아래 환경변수를 설정한 뒤 `npm run test:e2e`를 실행하세요.

| 환경변수        | 필수 | 설명                    |
| --------------- | ---- | ----------------------- |
| BASE_URL        | Y    | Amaranth10 도메인       |
| GROUP_SEQ       | Y    | 그룹 시퀀스             |
| CALLER_NAME     | Y    | 호출 구분명             |
| ACCESS_TOKEN    | Y    | 서버 인증 AccessToken   |
| HASH_KEY        | Y    | 서버 인증 HashKey       |
| SSO_ENCRYPT_KEY | N    | loginId/empSeq 암호화 키 (인증·전자결재 SSO 테스트 시 필요) |

`.env.example`을 복사해 `.env`로 만든 뒤 값을 채우면 됩니다. 테스트용 사용자: `loginId=admin`, `empSeq=1`.

```bash
cp .env.example .env
# .env 편집 후
npm run test:e2e
# 스킵 사유 확인 시: DEBUG_E2E=1 npm run test:e2e
```

## 사용 예시

### 클라이언트 생성 및 인증 토큰 발급

```ts
import { AmaranthClient, encryptForAuth } from 'amaranth-sdk';

const client = new AmaranthClient({
  baseUrl: 'https://dev.amaranth10.co.kr',
  accessToken: 'YOUR_ACCESS_TOKEN',
  hashKey: 'YOUR_HASH_KEY',
  callerName: 'APITEST',
  groupSeq: 'klagoDev',
  ssoEncryptKey: 'YOUR_SSO_ENCRYPT_KEY', // loginId/empSeq 암호화용
});

// 로그인ID로 인증 토큰 발급
const token = await client.getAuthTokenByLoginId('admin');
// 또는 empSeq로
const token2 = await client.getAuthTokenByEmpSeq('1');
```

### SSO (공통), 전자결재 SSO, 조직도 연동, 통합알림

```ts
// SSO 공통 (메뉴/팝업/URL 이동) — token은 getAuthToken 응답
await client.ssoCommon({
  authToken: token.authToken,
  hashKey: token.hashKey,
  groupSeq: client.groupSeq,
  type: 'url',
  url: '/#/popup?formId=1',
});

// 전자결재 SSO (작성/보기/삭제) — loginIdEnc는 encryptForAuth(loginId, ssoEncryptKey)로 생성
await client.ssoApproval({
  groupSeq: client.groupSeq,
  authToken: token.authToken,
  hashKey: token.hashKey,
  loginIdEnc: encryptForAuth('admin', 'YOUR_SSO_ENCRYPT_KEY'),
  appParams: { approKey: 'UB_xxx', mod: 'W', outProcessCode: 'CODE', loginId: 'admin' },
});

// 조직도 최초 연동
await client.orgSyncInitial({ groupSeq: 'klagoDev', syncCode: 'MY_SYSTEM', syncCompCd: '1000' });

// 통합알림
await client.sendNotification({
  eventType: 'CUST',
  eventSubType: 'CU001',
  groupSeq: 'klagoDev',
  compSeq: '1000',
  senderSeq: '1',
  alertYn: 'N',
  pushYn: 'N',
  portalYn: 'Y',
  recvEmpList: [{ empSeq: 1 }],
  data: { title: '제목', content: '내용' },
});
```

## API 대응

| api_docs | 구현 |
|----------|------|
| 2. authorization | `auth` — 인증 토큰 발급 |
| 3. sso | `sso` — SSO 공통, 전자결재(authUser) |
| 4. org-integrate | `org` — 최초연동(A03), 스케줄(A04), 연동완료(A05) |
| 6. notification | `notification` — 통합알림 |

## 라이선스

MIT