Edgelink
Docs전환 추적Node SDK (sdk-node)

Node SDK (sdk-node)

서버에서 매출(sale) 등 위변조 우려가 있는 전환 이벤트를 안전하게 전송하는 @edgelink/sdk-node 사용법

Node SDK (@edgelink/sdk-node)

@edgelink/sdk-node는 서버에서 매출(sale) 같이 위변조 우려가 있는 전환 이벤트를 secret 키로 안전하게 전송하는 SDK입니다.

참고: 본 SDK는 monorepo workspace 내부 의존성으로 제공됩니다. 외부 npm 배포(@edgelink org)는 별도 작업으로 진행 예정이며, 그 전까지는 본 문서의 코드 예시를 참고해 직접 HTTP 호출하거나 npm 배포 공지를 기다려 주세요.

설치 (npm 배포 후)

npm install @edgelink/sdk-node

npm 배포 전에는 본 문서의 API 레퍼런스를 참고하여 직접 HTTP 요청을 보내세요.

빠른 시작

import { Edgelink } from '@edgelink/sdk-node'

const edgelink = new Edgelink({
  secretKey: process.env.EDGELINK_SECRET_KEY!,
})

// 결제 완료 webhook
app.post('/api/checkout/success', async (req, res) => {
  await edgelink.conversions.create({
    clickId: req.cookies._el_cid,
    eventType: 'sale',
    eventName: 'purchase',
    externalEventId: order.id,
    valueMinor: order.totalAmountKrw,
    currency: 'KRW',
    customerEmailHash: Edgelink.hashEmail(user.email),
  })
  res.json({ ok: true })
})

핵심 정책

정책동작
secretKey 자동 픽업 안 함실수로 미설정 시 silent 동작을 막기 위해 명시적 주입을 강제합니다
clickId XOR externalUserId둘 중 하나 이상 반드시 전달. 타입 시그니처가 컴파일 타임에 강제
valueMinor 정수 강제최소 통화 단위 정수(KRW=원, USD=cents). Float 금지로 부동소수점 오차 차단
5xx/429 자동 재시도지수 백오프 최대 3회. Retry-After 헤더 존중
4xx 즉시 throw페이로드 오류는 재시도해도 실패하므로 즉시 전파
Edge runtime 호환native fetch만 사용 — Cloudflare Workers / Vercel Edge / Bun / Deno에서 동작

이벤트 타입별 사용 예시

1) 매출 (sale)

await edgelink.conversions.create({
  clickId: orderRecord.clickId, // DB에 저장해 둔 click ID
  eventType: 'sale',
  eventName: 'purchase',
  externalEventId: orderRecord.id, // 멱등키
  valueMinor: orderRecord.totalAmountKrw,
  currency: 'KRW',
})

2) 리드 — 서버 사이드 회원가입

브라우저가 아닌 서버에서 직접 회원가입을 처리하는 경우(예: B2B API):

await edgelink.conversions.create({
  externalUserId: newUser.id,
  eventType: 'lead',
  eventName: 'signup',
  customerEmailHash: Edgelink.hashEmail(newUser.email),
})

3) 멱등 재시도

같은 externalEventId로 재전송하면 200 + 기존 eventId가 반환되어 중복 저장되지 않습니다. 결제 webhook이 중복 도달하는 상황을 안전하게 처리할 수 있습니다.

에러 처리

SDK는 HTTP 상태에 따라 다음 에러 클래스를 throw 합니다:

import {
  EdgelinkAuthError,
  EdgelinkValidationError,
  EdgelinkRateLimitError,
  EdgelinkServerError,
} from '@edgelink/sdk-node'

try {
  await edgelink.conversions.create({...})
} catch (error) {
  if (error instanceof EdgelinkValidationError) {
    // 페이로드 오류 — 코드 수정 필요
    logger.error('Invalid payload', error.code, error.message)
  } else if (error instanceof EdgelinkRateLimitError) {
    // 큐에 다시 넣기. error.retryAfter 초 후 재시도
  } else if (error instanceof EdgelinkServerError) {
    // 5xx — 알림 후 모니터링
  }
}
에러HTTP의미
EdgelinkAuthError401 / 403키 누락·만료·회수·Origin 불일치
EdgelinkValidationError400 / 404 / 410페이로드 위반, click 미존재·만료
EdgelinkRateLimitError429retryAfter 초 정보 포함
EdgelinkServerError5xx서버 일시 장애

이메일 해싱 헬퍼

PII 보호를 위해 평문 이메일 대신 SHA-256 해시(lowercase)를 전송합니다.

const hash = Edgelink.hashEmail('User@Example.COM')
// → 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475857'

다음 단계