ppurio

뿌리오의 메세지 전송 연동을 위한 비공식 라이브러리입니다.

이 라이브러리는 Express와 같은 환경에서 직접 호출해서 사용할 수 있는 클래스 및 NestJS 모듈을 제공하며, 뿌리오 서비스로 메시지를 보내거나 예약한 메시지를 취소하는 기능을 제공합니다.

도움이 되셨다면 별 좀...(굽신굽신)

설치 방법

npm install ppurio

또는

yarn add ppurio

사용 방법

직접 호출하기

import { Ppurio } from 'ppurio';

const ppurio = new Ppurio('yourUserId');
const params = {
  sender: '01012345678',
  receiver: '01087654321', // 복수 전송시 ['01012341234', '01022223333'] 과 같은 배열
  message: '테스트 메시지입니다.',
};

ppurio.sendMessage(params).then(console.log);

NestJS 모듈로 사용하기

모듈 Import

import { PpurioModule } from 'ppurio';

모듈 등록

app.module.ts에서 PpurioModule을 import하고, forRoot() 메서드에 사용자 ID를 전달하여 모듈을 등록합니다.

@Module({
  imports: [PpurioModule.forRoot({ userId: 'yourUserId' })],
})
export class AppModule {}

forRootAsync()를 사용하여 비동기 방식으로 설정을 로드할 수도 있습니다.

@Module({
  imports: [
    PpurioModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        userId: configService.get('PPURIO_USER_ID'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

서비스 사용

PpurioService를 주입하여 뿌리오 서비스의 기능을 사용할 수 있습니다.

import { PpurioService } from 'ppurio';

@Injectable()
export class YourService {
  constructor(private readonly ppurioService: PpurioService) {}

  async someMethod() {
    const params = {
      sender: '01012345678',
      receiver: ['01087654321'],
      message: '테스트 메시지입니다.',
    };
    const result = await this.ppurioService.sendMessage(params);
    console.log(result);
  }
}

매서드

sendMessage(params: SendMessageParams) : SuccessSendMessage

const sendMessageParams = {
    sender: 'SENDER_PHONE_NUMBER',
    receiver: 'RECEIVER_PHONE_NUMBER',
    message: 'Your message goes here',
    // Optional parameters
    name: 'Name goes here',
    appointmentDate: '20190502093000',
    subject: 'Subject goes here',
    file1: '/path/to/your/file.jpg',
};

try {
    const result = await ppurio.sendMessage(sendMessageParams);
    console.log(result);
} catch (error) {
    console.error(error);
}

cancelReservation(params: CancelReservationParams) : SuccessCancelReservation

const cancelReservationParams = {
    messageId: 'YOUR_MESSAGE_ID',
};

try {
    const result = await ppurio.cancelReservation(cancelReservationParams);
    console.log(result);
} catch (error) {
    console.error(error);
}

오류 처리

Ppurio는 PpurioException을 던져서 API 호출에서 발생하는 오류를 처리합니다. 이 예외는 오류 메시지와 오류 코드를 포함합니다.

try {
  // Ppurio API call
} catch (error) {
  if (error instanceof PpurioException) {
    console.error(`An error occurred: ${error.message}, code: ${error.code}`);
  }
}

타입 및 에러 메시지

발송메세지 파라미터 (SendMessageParams)

속성명	타입	설명
sender	string	발신 번호 - 숫자만
receiver	string | string[]	수신 번호 - 여러명일 경우 배열로 입력
message	string	문자 내용 - 이름(name)값이 있다면 [이름]가 치환되서 발송됨
name	string | string[] (Optional)	이름 - 여러명일 경우 배열로 입력
appointmentDate	string (Optional)	예약 발송 (현재시간 기준 10분이후 예약가능) 작성 예: 20190502093000
subject	string (Optional)	제목 (최대 30byte)
file1	string (Optional)	이미지파일 경로 (jpg, jpeg만 지원 300 K 이하)

메세지 발송취소시 파라미터 (CancelReservationParams)

속성명	타입	설명
messageId	string	취소할 예약한 메세지ID

전송성공 리턴값 (SuccessSendMessage)

속성명	타입	설명
type	"sms" | "lms" | "mms"	전송된 메세지 형식
messageId	string	메세지 ID
okCount	number	성공한 횟수

예약취소 성공 리턴값 (SuccessCancelReservation)

속성명	타입	설명
okCount	number	성공한 횟수

에러 메시지 (errorMessages)

각 종류의 에러 메시지와 그에 대한 설명은 다음과 같습니다.

에러 메시지	설명
invalid_member	연동 서비스 신청이 안 됐거나 없는 아이디입니다.
under_maintenance	요청 시간에 서버 점검 중입니다.
allow_https_only	HTTP 요청입니다.
invalid_ip	등록된 접속 가능 IP가 아닙니다.
invalid_msg	문자 내용에 오류가 있습니다.
invalid_names	이름에 오류가 있습니다.
invalid_subject	제목에 오류가 있습니다.
invalid_sendtime	예약 발송 시간에 오류가 있습니다.
invalid_sendtime_maintenance	예약 발송 시간에 서버 점검 예정입니다.
invalid_phone	수신 번호에 오류가 있습니다.
invalid_msg_over_max	문자 내용이 너무 긴 경우입니다.
invalid_callback	발신 번호에 오류가 있습니다.
once_limit_over	1회 최대 발송 건수를 초과한 경우입니다.
daily_limit_over	1일 최대 발송 건수를 초과한 경우입니다.
not_enough_point	잔액이 부족한 경우입니다.
over_use_limit	한달 사용 금액을 초과한 경우입니다.
server_error	기타 서버 오류입니다.
invalid_msgid	발송 msgid에 오류가 있는 경우입니다.
master_not_exist	취소할 발송 요청이 없는 경우입니다.
not_update_time	예약 시간이 1분 이내여서 취소가 불가능한 경우입니다.
ing_master	이미 전송 중인 경우입니다.

참고

이 모듈은 뿌리오의 공식 라이브러리가 아닙니다. 이 모듈을 사용함으로써 발생하는 모든 문제에 대해서 뿌리오는 책임지지 않습니다.

문제 보고

이 라이브러리에 대한 버그 리포트나 기능 요청은 이슈 트래커를 이용해주세요.

라이센스

이 라이브러리는 MIT 라이센스 하에 배포됩니다.