@sendgo/node

import Sendgo from '@sendgo/node';

const sendgo = new Sendgo({
  accessKey:      process.env.SENDGO_ACCESS_KEY!,
  secretKey:      process.env.SENDGO_SECRET_KEY!,
  kakaoSenderKey: process.env.SENDGO_KAKAO_SENDER_KEY,
  smsSenderKey:   process.env.SENDGO_SMS_SENDER_KEY,
  apiVersion:     'v2',  // 'v1' | 'v2'
});

await sendgo.alimtalk.send({
  templateCode: 'ORDER_CONFIRM_001',  // Sendgo 승인 템플릿 코드
  contacts: [
    {
      contact: '01012345678',   // 수신자 전화번호 (필수)
      name:    '홍길동',        // 수신자 이름 (선택)
      var1:    'ORD-20260723-001',  // 템플릿 변수 #{var1}
      var2:    '스프링 부트 가이드', // 템플릿 변수 #{var2}
      var3:    '29,000원',          // 템플릿 변수 #{var3}
    },
  ],
});

await sendgo.alimtalk.send({
  templateCode: 'ORDER_CONFIRM_001',
  contacts: [{
    contact: '01012345678',
    name: '홍길동',
    var1: 'ORD-001',       // 주문번호
    var2: '맥북 프로',      // 상품명
    var3: '3,490,000원',   // 결제금액
    var4: '2026-07-25',    // 배송 예정일
  }],
});

await sendgo.alimtalk.send({
  templateCode: 'ORDER_CONFIRM_001',
  contacts: [
    { contact: '01011111111', var1: 'ORD-001' },
    { contact: '01022222222', var1: 'ORD-002' },
    { contact: '01033333333', var1: 'ORD-003' },
  ],
});

await sendgo.alimtalk.send({
  templateCode: 'PROMO_SUMMER_2026',
  scheduleType: 'SCHEDULED',
  at: '2026-07-28 09:00:00',  // 발송 예약 시각 (Y-m-d H:i:s)
  contacts: [{ contact: '01012345678', var1: '여름 한정 50% 할인' }],
});

await sendgo.alimtalk.send({
  templateCode: 'DELIVERY_START_001',
  replaceSms:  'Y',
  smsSubject:  '[배송 시작 안내]',
  smsContent:  '주문하신 상품이 출고되었습니다.\n송장번호: #{var2}',
  contacts: [{
    contact: '01012345678',
    var1: 'ORD-001',
    var2: '1234567890',  // 송장번호
  }],
});

// 기본 텍스트
await sendgo.friendtalk.send({
  content: '안녕하세요! 7월 한정 특가 이벤트를 확인해보세요. 최대 50% 할인!',
  contacts: [{ contact: '01012345678' }],
});

// 이미지 + 버튼
await sendgo.friendtalk.send({
  messageType: 'FI',
  content: '이번 주 특가 상품을 확인하세요!',
  imageUrl: 'https://cdn.example.com/banner.jpg',
  imageLink: 'https://example.com/event',
  buttons: [{
    name: '이벤트 보기',
    type: 'WL',
    linkMo: 'https://example.com/event',
    linkPc: 'https://example.com/event',
  }],
  contacts: [{ contact: '01012345678' }],
});

// SMS — 단문 (90자 이하)
await sendgo.sms.sendSms({
  content: '[Sendgo] 인증번호: 123456 (5분 이내 입력)',
  contacts: [{ contact: '01012345678' }],
});

// LMS — 장문 (제목 포함)
await sendgo.sms.sendLms({
  subject: '[중요] 서비스 점검 안내',
  content: `안녕하세요.
서비스 점검이 예정되어 있습니다.

■ 점검 일시: 2026-07-25 02:00 ~ 06:00
■ 영향 범위: 전체 서비스

이용에 불편을 드려 죄송합니다.`,
  contacts: [{ contact: '01012345678' }],
});

// MMS — 멀티미디어
await sendgo.sms.sendMms({
  subject: '[이벤트] 7월 특가',
  content: '이번 달 특가 상품을 확인하세요!',
  contacts: [{ contact: '01012345678' }],
});

// 단건 발송 — 채널 친구 대상
await sendgo.brandMessage.send({
  targeting: 'M',
  messageType: 'FL',
  friendTemplateUuid: '9cd5460b-6458-4edc-9b11-c26d3013c340',
  contacts: [{ contact: '01012345678', var1: '29,000원' }],
});

// 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 불필요)
await sendgo.brandMessage.broadcast({
  messageType: 'FW',
  friendTemplateUuid: '9cd5460b-6458-4edc-9b11-c26d3013c340',
});

// 캠페인 조회
const list = await sendgo.brandMessage.campaigns({ count: 10 });
const one  = await sendgo.brandMessage.campaign('1f0a6d0e-6b3b-4f0f-9b2f-2f6f6a1b7c11');

// app/api/notify/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Sendgo from '@sendgo/node';

// 싱글톤 패턴으로 API Route 간 재사용
const sendgo = new Sendgo({
  accessKey:      process.env.SENDGO_ACCESS_KEY!,
  secretKey:      process.env.SENDGO_SECRET_KEY!,
  kakaoSenderKey: process.env.SENDGO_KAKAO_SENDER_KEY,
  apiVersion:     'v2',
});

export async function POST(request: NextRequest) {
  const { phone, orderNumber } = await request.json();

  await sendgo.alimtalk.send({
    templateCode: 'ORDER_CONFIRM_001',
    contacts: [{ contact: phone, var1: orderNumber }],
  });

  return NextResponse.json({ success: true });
}

// app/actions/notification.ts — Server Actions
'use server';
import Sendgo from '@sendgo/node';

const sendgo = new Sendgo({ /* ... */ });

export async function sendOrderConfirm(phone: string, orderNumber: string) {
  return sendgo.alimtalk.send({
    templateCode: 'ORDER_CONFIRM_001',
    contacts: [{ contact: phone, var1: orderNumber }],
  });
}

import express from 'express';
import Sendgo from '@sendgo/node';

const app = express();
const sendgo = new Sendgo({
  accessKey: process.env.SENDGO_ACCESS_KEY!,
  secretKey: process.env.SENDGO_SECRET_KEY!,
  kakaoSenderKey: process.env.SENDGO_KAKAO_SENDER_KEY,
});

app.use(express.json());

app.post('/api/notify', async (req, res) => {
  const { phone, orderNumber } = req.body;
  await sendgo.alimtalk.send({
    templateCode: 'ORDER_CONFIRM_001',
    contacts: [{ contact: phone, var1: orderNumber }],
  });
  res.json({ success: true });
});

// sendgo.module.ts
import { Module, Global } from '@nestjs/common';
import Sendgo from '@sendgo/node';

@Global()
@Module({
  providers: [{
    provide: 'SENDGO_CLIENT',
    useFactory: () => new Sendgo({
      accessKey:      process.env.SENDGO_ACCESS_KEY!,
      secretKey:      process.env.SENDGO_SECRET_KEY!,
      kakaoSenderKey: process.env.SENDGO_KAKAO_SENDER_KEY,
      apiVersion:     'v2',
    }),
  }],
  exports: ['SENDGO_CLIENT'],
})
export class SendgoModule {}

// notification.service.ts
@Injectable()
export class NotificationService {
  constructor(@Inject('SENDGO_CLIENT') private readonly sendgo: Sendgo) {}

  async sendOrderConfirm(phone: string, orderNumber: string) {
    return this.sendgo.alimtalk.send({
      templateCode: 'ORDER_CONFIRM_001',
      contacts: [{ contact: phone, var1: orderNumber }],
    });
  }
}

import Fastify from 'fastify';
import Sendgo from '@sendgo/node';

const app = Fastify();
const sendgo = new Sendgo({ accessKey: '...', secretKey: '...' });

app.post('/notify', async (request, reply) => {
  const { phone, orderNumber } = request.body as any;
  await sendgo.alimtalk.send({
    templateCode: 'ORDER_CONFIRM_001',
    contacts: [{ contact: phone, var1: orderNumber }],
  });
  return { success: true };
});

import type {
  SendgoConfig,      // 클라이언트 설정
  Contact,           // 수신자 정보
  AlimtalkParams,    // 알림톡 발송 파라미터
  FriendtalkParams,  // 친구톡 발송 파라미터
  SmsParams,         // SMS 발송 파라미터
  SendgoResponse,    // API 응답
  ScheduleType,      // 'DIRECTLY' | 'SCHEDULED'
  SmsMessageType,    // 'SMS' | 'LMS' | 'MMS'
  FriendtalkMessageType, // 'FT' | 'FI' | 'FW' | ...
} from '@sendgo/node';

import { SendgoError } from '@sendgo/node';

try {
  await sendgo.alimtalk.send({ ... });
} catch (error) {
  if (error instanceof SendgoError) {
    console.error({
      statusCode: error.statusCode,   // HTTP 상태 코드
      errorCode:  error.errorCode,    // Sendgo 에러 코드
      message:    error.message,      // 에러 메시지
      endpoint:   error.endpoint,     // 호출된 엔드포인트
    });

    switch (error.errorCode) {
      case 'INVALID_TEMPLATE_CODE': /* 템플릿 코드 확인 */ break;
      case 'PAYMENT_REQUIRED':      /* 크레딧 충전 알림 */ break;
      case 'EMPTY_CONTACTS':        /* 수신자 확인 */      break;
    }
  }
}

// 짧은 URL 생성 (v2 전용)
const created = await sendgo.shortUrl.create({
  targetUrl: 'https://example.com/promotions/summer-sale',
  title: '여름 세일 랜딩',
});

const { code, shortUrl } = created.data;

// 반응 통계 — 일별 추이 + 디바이스/유입경로/국가별 분해
const stats = await sendgo.shortUrl.stats(code, { from: '2026-08-01' });

await sendgo.shortUrl.list({ count: 10 });
await sendgo.shortUrl.show(code);
await sendgo.shortUrl.deactivate(code);   // 리다이렉트만 중지, 통계는 남는다

// 1단계 — 카카오가 관리자 휴대폰으로 인증번호를 SMS 발송한다 (응답에 번호는 없다)
await sendgo.kakaoSenders.requestToken('@my-channel', '01012345678');

// 2단계 — 사람이 받은 인증번호로 발신프로필 생성
const created = await sendgo.kakaoSenders.create({
  token: '123456',
  yellowId: '@my-channel',
  phoneNumber: '01012345678',
  categoryCode: '001001',          // categories() 로 조회
});

const kakaoSenderKey = created.data.sender.kakaoSenderKey;

await sendgo.kakaoSenders.categories();
await sendgo.kakaoSenders.list();
await sendgo.kakaoSenders.sync();               // 전체 상태 동기화 (하루 한 번 권장)
await sendgo.kakaoSenders.sync(kakaoSenderKey); // 단건

const created = await sendgo.noticeTemplates.create({
  kakaoSenderKey,
  templateName: '주문 접수 안내',
  templateContent: '#{name}님, 주문 #{orderNo}이 접수되었습니다.',
  templateMessageType: 'BA',       // BA 기본형 / EX 부가정보형 / AD 채널추가형 / MI 복합형
  templateEmphasizeType: 'NONE',   // NONE / TEXT / ITEM_LIST / IMAGE
  categoryCode: '001001',

  // sendgo 자체 정책 게이트 — 카카오 심사와 별개이며 빠뜨리면 거절된다
  messagePurpose: 'order_delivery',
  legalBasis: 'transaction',
  benefitOrigin: 'none',
  expiryType: 'none',
  optInReviewConfirmed: true,
  ctaClearConfirmed: true,
  policyConfirmed: true,
});

const templateCode = created.data.template.templateCode;

// 검수 요청 — 증빙이 필요하면 파일도 붙인다 (첨부가 있으면 comment 필수)
await sendgo.noticeTemplates.requestInspection(templateCode);

// 결과는 비동기다. 웹훅이 없으므로 폴링한다
const synced = await sendgo.noticeTemplates.sync(templateCode);
synced.data.template.inspectionStatus;   // REG → REQ → APR / REJ

await sendgo.noticeTemplates.list({ kakaoSenderKey, inspectionStatus: 'APR' });
await sendgo.noticeTemplates.show(templateCode);
await sendgo.noticeTemplates.update(templateCode, { /* ... */ });  // 본문이 바뀌면 재검수 필요
await sendgo.noticeTemplates.cancelInspection(templateCode);
await sendgo.noticeTemplates.cancelApproval(templateCode);
await sendgo.noticeTemplates.release(templateCode);                // 휴면 해제
await sendgo.noticeTemplates.delete(templateCode);                 // sendgo 목록에서만 삭제된다
await sendgo.noticeTemplates.categories();

import { readFile } from 'node:fs/promises';

const image = { value: new Blob([await readFile('banner.jpg')]), filename: 'banner.jpg' };

await sendgo.noticeTemplates.createWithImage({ /* ...필드 동일 */ }, image);
await sendgo.noticeTemplates.requestInspection(templateCode, '주문 확인 화면 첨부', [image]);

const created = await sendgo.brandTemplates.create({
  kakaoSenderKey,
  templateName: '여름 세일 안내',
  templateType: 'FI',              // FT/FI/FW/FL/FC/FM/FP/FA — 서버가 chatBubbleType 으로 변환
  templateContent: '여름 세일이 시작되었습니다.',
  imageUrl: 'https://mud-kage.kakao.com/....jpg',
});

// 동보 발송(targeting=F)에는 변수가 없는 템플릿만 쓸 수 있다
created.data.template.containsVariables;

await sendgo.brandTemplates.list({ kakaoSenderKey });
await sendgo.brandTemplates.sync(templateCode);
await sendgo.brandTemplates.import(kakaoSenderKey);   // 카카오에 있는 템플릿 가져오기
await sendgo.brandTemplates.delete(templateCode);     // 카카오에서도 삭제된다

import { readFile } from 'node:fs/promises';

// 계정 종류에 맞는 유형과 유형별 필수 서류
await sendgo.senderRegistration.numberTypes();

// 형식·중복 미리 확인
const check = await sendgo.senderRegistration.validate('02-1234-5678', 'team_main');

const created = await sendgo.senderRegistration.create(
  {
    senderAlias: '고객센터 대표번호',
    senderNumberType: 'team_main',   // personal_other / team_main / team_other_company
    phoneE164: '02-1234-5678',
    // check.data.duplicationReasonRequired 가 true 면 필수
    // duplicationReason: '부서별 분리 운영',
  },
  {
    csuCertificate: {
      value: new Blob([await readFile('csu.pdf')]),
      filename: 'csu.pdf',
    },
  },
);

created.data.sender.status;   // PENDING — 운영자 승인 후 SUCCESS

await sendgo.senderRegistration.list();
await sendgo.senderRegistration.update(senderKey, { senderAlias: '새 이름' });
await sendgo.senderRegistration.delete(senderKey);

await sendgo.messageTemplates.create({
  messageTranType: 'LMS',
  messageTranSubject: '주문 안내',   // LMS·MMS 는 필수
  messageTranMsg: '주문이 접수되었습니다.',
});

await sendgo.messageTemplates.list({ messageType: 'LMS' });
await sendgo.messageTemplates.update(templateKey, { /* ... */ });
await sendgo.messageTemplates.delete(templateKey);

const created = await sendgo.webhook.subscribe({
  url: 'https://reseller.example.com/hooks/sendgo',
});

// 시크릿은 이 응답에서 한 번만 나온다. 즉시 저장한다.
const secret = created.data.secret;

await sendgo.webhook.show();          // 구독 설정 + 마지막 전송 결과
await sendgo.webhook.test();          // 배선 확인
await sendgo.webhook.unsubscribe();

import express from 'express';
import { WebhookService } from '@sendgo/node';

app.post('/hooks/sendgo', express.raw({ type: 'application/json' }), (req, res) => {
  if (!WebhookService.verifySignature(req.body, req.get('X-Sendgo-Signature') ?? '', secret)) {
    return res.sendStatus(401);
  }

  const { event, data, deliveryId } = JSON.parse(req.body.toString('utf8'));

  // 같은 이벤트가 두 번 올 수 있다 — deliveryId 로 걸러낸다.
  queue.add(event, { data, deliveryId });

  res.sendStatus(204);   // 처리는 큐로. 여기서 오래 끌면 재시도가 쌓인다.
});

import { readFile } from 'node:fs/promises';

const uploaded = await sendgo.kakaoImages.upload('default', {
  value: new Blob([await readFile('banner.jpg')]),
  filename: 'banner.jpg',
});

await sendgo.brandTemplates.create({
  kakaoSenderKey,
  templateName: '여름 세일 안내',
  templateType: 'FI',
  imageUrl: uploaded.data.imageUrl,
});

await sendgo.kakaoImages.uploadMany('carousel_feed', [slide1, slide2, slide3]);
await sendgo.kakaoImages.types();   // 유형별 필드·최대 개수

// 증분만 가져간다. 하루 한 번이면 충분하다.
await sendgo.rejectedNumbers.list({ since: '2026-09-01', count: 500 });

import { AccountClient } from '@sendgo/node';
const account = new AccountClient({ agentToken: process.env.SENDGO_AGENT_TOKEN! });
const result = await account.me();
await account.selectOrganization('team-uuid');
const issued = await account.createApiKey({ name: '서버 연동' });

const folders = await sendgo.templateFolders.list({ templateType: 'notice' });
const created = await sendgo.templateFolders.create({ name: '주문 안내' });
await sendgo.templateFolders.assign({
  templateType: 'notice', kakaoSenderKey, templateCodes: ['ORDER_001'], folderUuid: null,
});
await sendgo.noticeTemplates.list({ folderUuid: 'none' });