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
│   ├── 7. org-cud-api.md
│   └── 8. approval-r-api.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)
│   ├── org-cud/         # 조직도 등록/수정/삭제 (A06)
│   ├── approval/        # 전자결재(영리) 조회 (api99u02A01~A04)
│   └── 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' });

// 조직도 CUD(A06): 현재 공개된 기능은 "사원 비밀번호 변경"뿐입니다.
//   회사/사업장/부서/사원/직급·직책 등록·수정·삭제는 src/org-cud 에 구현되어 있으나 공개 API에서 잠금 상태.
// 사원 비밀번호 변경 — empSave 기반이라 대상 사원의 현재 정보(EmpSaveParams) + 새 비밀번호를 함께 전달.
//   apiType/header·body 래퍼는 SDK가 자동 주입. 실패 시 resultCode와 함께 예외(throw).
await client.orgChangeEmpPassword({
  emp: {
    empSeq: '56823', // 대상 사원 시퀀스 (수정)
    empSeqDef: '',
    empName: '홍길동',
    empRealName: '홍길동',
    loginId: 'hong',
    emailAddr: 'hong',
    genderCode: 'M',
    nativeLangCode: 'kr',
    empJoinDay: '20240101',
    licenseCheckYn: '1',
    licenseInfo: 'PRO',
    mailUseYn: 'Y',
    oneAiYn: 'N',
    ocSearchYn: 'N',
    crmYn: 'Y',
    useYn: 'Y',
    messengerUseYn: 'Y',
    mobileUseYn: 'Y',
    signType: 'stamp',
    empDeptList: [
      {
        compSeq: '1000', deptSeq: '2019', deptSeqNew: '', erpEmpSeq: 'E1',
        mainCompYn: 'Y', mainDeptYn: 'Y', positionCode: '001', dutyCode: '001',
        workStatus: 'J05', statusCode: '001', jobCode: '001',
        empDeptJoinDay: '20240101', orgchartDisplayYn: 'Y',
        messengerDisplayYn: 'Y', checkWorkYn: 'Y',
      },
    ],
  },
  newLoginPassword: 'newLoginPw!1', // 로그인 비밀번호 (선택)
  newApprPassword: 'newApprPw!2',   // 결재 비밀번호 (선택). 둘 중 최소 하나 필수
});

// 전자결재(영리) 조회 — 결재함/문서목록/결재라인/문서상세 (api99u02A01~A04)
//   조회 전용. 실패 시 top-level resultCode와 함께 예외(throw). empSeq는 조회 주체 사용자.

// 1) 결재함 조회 (카운트 포함) → boxList 반환
const boxes = await client.getApprovalBoxes({
  empSeq: '1',
  companyInfo: { compSeq: '1000', deptSeq: '100001304267', bizSeq: '1000' },
});

// 2) 결재 문서 목록 조회 → { eaDocList, totalCnt } (totalCnt는 페이징 신호)
const docList = await client.getApprovalDocList({
  empSeq: '1',
  menuId: boxes?.[0]?.menuId ?? '1000400', // 결재함 menuId
  companyInfo: { compSeq: '1000', deptSeq: '100001364455' },
  fromDt: '2024-01-01',
  toDt: '2024-12-31',
  page: '1',
  pageSize: '30',
  sort: '30', // 10 상신일, 20 결재일, 30 종결일
  docStsList: [{ docSts: '20' }, { docSts: '90' }],
  langCode: 'kr',
});

// 3) 결재라인 조회 → docLineList 반환
const line = await client.getApprovalLine({
  empSeq: '1',
  docId: '142371',
  companyInfo: { compSeq: '1000', deptSeq: '100001300502' },
});

// 4) 결재문서 상세 조회 → 문서 HTML(contents)·버튼·첨부 등 (header pId/tId는 SDK가 자동 주입)
const detail = await client.getApprovalDocDetail({
  empSeq: '1',
  docId: '145146',
  companyInfo: { compSeq: '1000', deptSeq: '100001364455' },
  langCode: 'kr',
});

// 통합알림
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 — 통합알림 | | 8. approval-r-api | approval — 전자결재(영리) 조회: 결재함(A01), 문서목록(A02), 결재라인(A03), 문서상세(A04) | | 7. org-cud-api | org-cud — 사원 비밀번호 변경(orgChangeEmpPassword)만 공개. 회사/사업장/부서/사원/직급·직책 등록·수정·삭제는 구현되어 있으나 공개 API에서 잠금(A06) |

라이선스

MIT

📦 배포 (자동)

이 패키지(@lumir-company/amaranth-sdk)는 release-please + self-hosted GitHub Actions 러너로 자동 배포됩니다. 버전을 수동으로 올리거나 npm publish를 직접 실행할 필요가 없습니다.

버전 규칙 (Semantic Versioning)

커밋 메시지(Conventional Commits)가 다음 버전을 자동 결정합니다:

| 커밋 prefix | 버전 증가 | 예시 | | --- | --- | --- | | fix: … | patch | 1.2.3 → 1.2.4 | | feat: … | minor | 1.2.3 → 1.3.0 | | feat!: … 또는 본문 BREAKING CHANGE: | major | 1.2.3 → 2.0.0 | | chore: docs: refactor: test: 등 | 릴리스 없음 | — |

배포 흐름

1. main 브랜치에 conventional commit을 push 한다.
2. release-please가 chore(main): release X.Y.Z 형태의 Release PR을 자동 생성한다 (버전 bump + CHANGELOG.md 갱신).
3. 그 PR을 검토 후 머지한다. ← 사람이 하는 유일한 단계
4. 머지되면 자동으로 Git 태그 + GitHub Release 생성 + npm publish 가 실행된다 (.github/workflows/release.yml, self-hosted 러너 lumir-ci).

npm 인증은 repo secret NPM_TOKEN(Automation/Publish 토큰), release-please는 RELEASE_PLEASE_TOKEN(PAT)을 사용한다.