Amaranth10 API SDK

Amaranth10 그룹웨어 API 연동용 TypeScript SDK입니다.
API 명세는 api_docs/ 문서를 기준으로 합니다.

설치

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

설치 및 빌드

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.

cp .env.example .env
# .env 편집 후
npm run test:e2e
# 스킵 사유 확인 시: DEBUG_E2E=1 npm run test:e2e

사용 예시

클라이언트 생성 및 인증 토큰 발급

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, 조직도 연동, 통합알림

// 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