npm package: @lumir-company/lsms-server-api
Description: LSMS Server API Client Library
Author: LSMS Team
Latest version: 0.2.17

# LSMS Server API Client

LSMS (Laboratory Schedule Management System) Server API 클라이언트 라이브러리입니다.

## 설치

```bash
npm install @lsms/server-api
```

## 사용법

### 기본 사용법

```typescript
import { AuthAPI, UsersAPI, ReservationsAPI } from '@lsms/server-api';

// API 클라이언트 초기화
// baseUrl은 API 서버의 기본 URL을 입력합니다 (예: https://api.lsms.example.com/api/v2)
const authAPI = new AuthAPI('https://api.lsms.example.com/api/v2');
const usersAPI = new UsersAPI('https://api.lsms.example.com/api/v2');
const reservationsAPI = new ReservationsAPI('https://api.lsms.example.com/api/v2');

// 로그인
const loginResponse = await authAPI.login({
  accountId: 'user@example.com',
  password: 'password123',
});

if (loginResponse.success) {
  console.log('로그인 성공:', loginResponse.data);
  // 토큰 자동 설정됨
}
```

### 개별 API 사용

```typescript
import {
  AuthAPI,
  UsersAPI,
  ReservationsAPI,
  AdminReservationsAPI,
  ResourcesAPI,
  ResourceGroupsAPI,
  NotificationsAPI,
  FilesAPI,
  ScheduleAPI,
  ConsumablesAPI,
  DepartmentsAPI,
  EmployeesAPI,
  InquiriesAPI,
  TasksAPI,
} from '@lsms/server-api';

// API 클라이언트 초기화
// baseUrl은 API 서버의 기본 URL을 입력합니다
// 예: https://api.lsms.example.com/api/v2
const authAPI = new AuthAPI('https://api.lsms.example.com/api/v2');
const usersAPI = new UsersAPI('https://api.lsms.example.com/api/v2');
const reservationsAPI = new ReservationsAPI('https://api.lsms.example.com/api/v2');
const adminReservationsAPI = new AdminReservationsAPI('https://api.lsms.example.com/api/v2');

// 토큰 설정 (로그인 후 자동으로 설정되지만 수동 설정도 가능)
authAPI.setToken('your-access-token');
usersAPI.setToken('your-access-token');
reservationsAPI.setToken('your-access-token');
adminReservationsAPI.setToken('your-access-token');
```

## API 모듈

### 인증 (Auth)

- 로그인/로그아웃
- 토큰 갱신
- 현재 사용자 정보 조회

### 사용자 (Users)

- 사용자 목록 조회
- 사용자 정보 조회/수정
- 비밀번호 변경
- 알림 설정 관리
- 프로필 업데이트

### 예약 (Reservations)

- 예약 생성/수정/삭제
- 예약 상세 조회
- 예약 상태 변경
- 내 예약 목록 조회
- 캘린더 예약 조회
- 예약 연장/연장 가능 여부 확인
- 스냅샷 생성/조회/삭제

### 관리자 예약 (Admin Reservations)

- 관리자 예약 목록 조회
- 확인이 필요한 예약 조회
- 예약 검증
- 관리자 캘린더 조회
- 예약 승인/거부
- 차량 반납 처리
- 예약 통계 조회
- 예약 일괄 처리
- 예약 연장 (관리자 전용)

### 자원 (Resources)

- 자원 목록 조회
- 자원 상세 조회
- 자원 생성/수정/삭제
- 자원 그룹별 조회
- 자원 가용성 조회
- 자원 예약 가능 시간 조회
- 자원 순서 변경
- 자원 예약 가능 상태 수정
- 월별 예약 가용성 확인

### 자원 그룹 (Resource Groups)

- 부모 자원 그룹 조회 (일반/관리자)
- 자원 그룹별 자원 조회 (일반/관리자)
- 자원 그룹 생성/수정/삭제 (관리자)
- 자원 그룹 순서 변경 (관리자)
- 자원 그룹 상세 조회

### 일정 (Schedule)

- 일정 생성/수정/삭제
- 일정 캘린더 조회
- 일정 상세 조회
- 내 일정 조회
- 자원별 일정 조회
- 일정 취소/완료
- 일정 연장/연장 가능 확인
- 내 일정 내역 조회

### 알림 (Notifications)

- 알림 목록 조회
- 알림 상세 조회
- 알림 읽음 처리 (단일/일괄/전체)
- 알림 삭제 (단일/일괄)
- 읽지 않은 알림 개수 조회
- 알림 설정 조회/변경
- 웹 푸시 구독/해제
- 알림 전송 (관리자용)

### 파일 (Files)

- 파일 업로드 (일반/Presigned URL)
- 파일 목록 조회
- 파일 상세 조회
- 파일 다운로드 URL 조회
- 파일 삭제 (단일/일괄)
- 파일 메타데이터 수정
- 파일 통계 조회

### 소모품 (Consumables)

- 소모품 목록 조회
- 소모품 상세 조회
- 소모품 정보 수정

### 부서 (Departments)

- 하위 부서 목록 조회

### 직원 (Employees)

- 부서별 직원 목록 조회

### 문의 (Inquiries)

- 문의 생성

### 태스크 (Tasks)

- 태스크 목록 조회

## 타입 정의

모든 API 요청/응답에 대한 TypeScript 타입이 포함되어 있습니다:

```typescript
import type {
  // 인증 관련
  LoginRequest,
  LoginResponse,

  // 사용자 관련
  User,
  UserListQueryParams,
  ChangePasswordRequest,
  NotificationSettingsRequest,

  // 예약 관련
  Reservation,
  ReservationRequest,
  ReservationUpdateRequest,
  MyReservationsQuery,
  CalendarReservationsRequest,
  ExtendReservationRequest,
  SnapshotRequest,

  // 관리자 예약 관련
  AdminReservation,
  AdminReservationsQuery,
  ReservationCheckRequest,
  ReservationApprovalRequest,
  BulkReservationAction,
  ReservationStats,

  // 자원 관련
  Resource,
  ResourceGroup,
  ResourceListQueryParams,
  CreateResourceRequest,
  ResourceAvailabilityRequest,

  // 일정 관련
  ScheduleCreateRequestDto,
  ScheduleCalendarRequest,
  ScheduleDetailRequest,
  MyScheduleRequest,
  ResourceScheduleRequest,
  ScheduleUpdateRequestDto,

  // 알림 관련
  Notification,
  NotificationListQuery,
  SendNotificationRequest,
  WebPushSubscription,

  // 파일 관련
  FileUploadRequest,
  FileUploadResponse,
  PresignedUploadRequest,
  FileListQuery,

  // 소모품 관련
  ConsumableResponseDto,
  MaintenanceResponseDto,
  ConsumableListRequest,

  // 부서 관련
  SubDepartment,
  SubDepartmentsRequest,

  // 직원 관련
  EmployeeInfo,
  EmployeesByDepartmentResponseDto,

  // 문의 관련
  InquiryCreateRequestDto,
  InquiryCreateResponseDto,

  // 태스크 관련
  TaskItem,
  TaskListResponse,
  TaskListQueryParams,
} from '@lsms/server-api';
```

## 사용 예시

### 예약 관리

```typescript
import { ReservationsAPI } from '@lsms/server-api';

const reservationsAPI = new ReservationsAPI('https://api.lsms.example.com/api/v2');

// 예약 생성
const newReservation = await reservationsAPI.createReservation({
  resourceId: 'resource-123',
  startTime: '2024-01-15T09:00:00Z',
  endTime: '2024-01-15T10:00:00Z',
  purpose: '회의실 사용',
  participants: 5,
  notes: '중요한 회의',
});

// 내 예약 목록 조회
const myReservations = await reservationsAPI.getMyReservations({
  status: 'CONFIRMED',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
});
```

### 관리자 예약 관리

```typescript
import { AdminReservationsAPI } from '@lsms/server-api';

const adminReservationsAPI = new AdminReservationsAPI('https://api.lsms.example.com/api/v2');

// 확인이 필요한 예약 조회
const pendingReservations = await adminReservationsAPI.getPendingReservations();

// 예약 승인
const approvalResult = await adminReservationsAPI.approveOrRejectReservation('reservation-123', {
  action: 'approve',
  reason: '승인 완료',
  adminNotes: '관리자 승인',
});

// 예약 통계 조회
const stats = await adminReservationsAPI.getReservationStats('2024-01-01', '2024-01-31', 'department-123');
```

### 파일 관리

```typescript
import { FilesAPI } from '@lsms/server-api';

const filesAPI = new FilesAPI('https://api.lsms.example.com/api/v2');

// 파일 업로드
const uploadResult = await filesAPI.uploadFile({
  file: fileObject,
  fileName: 'document.pdf',
  mimeType: 'application/pdf',
  category: 'documents',
  isPublic: false,
});

// Presigned URL을 이용한 업로드
const presignedUrl = await filesAPI.getPresignedUploadUrl({
  fileName: 'large-file.zip',
  mimeType: 'application/zip',
  fileSize: 1024000,
  category: 'uploads',
});
```

### 알림 관리

```typescript
import { NotificationsAPI } from '@lsms/server-api';

const notificationsAPI = new NotificationsAPI('https://api.lsms.example.com/api/v2');

// 알림 목록 조회
const notifications = await notificationsAPI.getNotifications({
  isRead: false,
  type: 'INFO',
  category: 'RESERVATION',
});

// 알림 읽음 처리
await notificationsAPI.markAsRead('notification-123');

// 웹 푸시 구독
await notificationsAPI.subscribeWebPush({
  endpoint: 'https://fcm.googleapis.com/fcm/send/...',
  keys: {
    p256dh: 'key1',
    auth: 'key2',
  },
});
```

## 라이선스

MIT

## 기여

이슈나 풀 리퀘스트는 언제든 환영합니다!