@edgelinkapp/sdk-node

Edgelink 전환 추적용 서버 SDK. 결제 완료처럼 위변조 우려가 있는 이벤트를 secret 키로 안전하게 전송합니다.

설치

npm install @edgelinkapp/sdk-node

ESM(import)과 CJS(require)를 모두 지원하며 TypeScript 타입이 포함되어 있습니다. native fetch만 사용하므로 Node 18+ / Cloudflare Workers / Vercel Edge / Bun / Deno에서 동일하게 동작합니다.

사용법

import { Edgelink } from '@edgelinkapp/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, // KRW=원 정수. Float 금지
    currency: 'KRW',
    customerEmailHash: Edgelink.hashEmail(user.email),
  })
  res.json({ ok: true })
})

핵심 정책

• secretKey는 명시적으로 주입합니다 (process.env 자동 픽업 없음 — 실수로 미설정 시 silent 동작 방지).
• clickId 또는 externalUserId 중 하나 이상 필수 (TypeScript 타입 시그니처가 강제).
• valueMinor는 최소 통화 단위 정수 (KRW=원, USD=cents). Float 금지.
• 5xx/429 응답은 지수 백오프로 자동 재시도 (기본 3회). 4xx는 즉시 throw.

에러 클래스

| 에러 | 상황 | | ------------------------- | ---------------------------------------------- | | EdgelinkAuthError | 401/403 — 키 누락/만료/회수/Origin 불일치 | | EdgelinkValidationError | 400/404/410 — 페이로드 위반, click 미존재/만료 | | EdgelinkRateLimitError | 429 — retryAfter 초 정보 포함 | | EdgelinkServerError | 5xx — 서버 일시 장애 |

Edge runtime 호환

native fetch만 사용합니다. Cloudflare Workers / Vercel Edge / Bun / Deno에서 동일하게 동작합니다.