설치와 초기화

설치

npm install @apicook/sdk

pnpm add @apicook/sdk

의존성이 없는 단일 패키지이고, 타입 정의가 함께 들어 있어 @types/...를 따로 설치할 필요가 없습니다.

초기화

import { ApiCook } from '@apicook/sdk';

const cook = new ApiCook('your-project-id', {
    apiKey: process.env.APICOOK_API_KEY!,
});

projectId와 apiKey는 필수입니다. 둘 중 하나라도 비어 있으면 생성자가 그 자리에서 ApiCookError를 던집니다 — 첫 호출까지 기다리지 않으므로, 환경변수를 빠뜨렸다면 앱 시작 시점에 바로 드러납니다.

인스턴스는 한 번 만들어 재사용하세요. 설정 JSON 캐시와 인증 파라미터가 인스턴스에 붙어 있어서, 요청마다 새로 만들면 매번 설정을 다시 내려받게 됩니다.

// lib/apicook.ts — 모듈 스코프에 한 번
export const cook = new ApiCook(process.env.APICOOK_PROJECT_ID!, {
    apiKey: process.env.APICOOK_API_KEY!,
});

옵션 전체

옵션	타입	기본값	설명
apiKey	string	—	필수. SDK API 키(apk_...)
mode	'direct' | 'proxy'	환경 자동 감지	동작 모드
cdnBase	string	https://api.apicook.dev	설정 JSON을 받아올 주소
proxyBase	string	cdnBase와 동일	프록시 서버 주소
cacheTtlMs	number	60000	설정 JSON 캐시 수명(ms)
verifySignature	boolean	true	설정 JSON 서명 검증. direct 모드에서만 동작
telemetry	boolean	false	direct 모드 사용량 수집 opt-in
telemetryBase	string	cdnBase와 동일	텔레메트리 수신 주소

mode

지정하지 않으면 SDK가 실행 환경을 봅니다. 전역에 window와 document가 둘 다 있으면 브라우저로 판단해 proxy, 아니면 direct가 됩니다.

이 감지에 걸리는 애매한 환경들이 있습니다. jsdom을 쓰는 테스트 환경은 window가 있어 proxy로 잡히고, 일부 SSR 프레임워크의 전역 폴리필도 마찬가지입니다. 의도와 다르게 동작한다면 명시하세요.

const cook = new ApiCook('project-id', {
    apiKey: 'apk_...',
    mode: 'direct',   // 감지에 맡기지 않는다
});

cacheTtlMs

설정 JSON을 메모리에 얼마나 들고 있을지입니다. 기본 60초는 "배포 후 1분 안에는 새 규칙이 적용된다"는 뜻이기도 합니다.

값을 키우면 설정 요청이 줄지만 규칙 변경 반영이 늦어집니다. 개발 중에 규칙을 자주 고친다면 cook.refresh()로 즉시 갱신하는 편이 낫습니다.

verifySignature

기본값은 true입니다. 설정 JSON에 실린 HMAC 서명을 SDK가 검증해, 전송 중 규칙이 변조되지 않았는지 확인합니다. 검증에 실패하면 호출이 진행되지 않고 예외가 납니다.

direct 모드에서만 동작합니다. proxy 모드는 애초에 설정 JSON을 내려받지 않고 서버가 규칙을 적용하므로 검증할 대상이 없습니다.

끄는 것이 정당한 경우는 하나뿐입니다. 직접 운영하는 CDN이나 프록시가 JSON 본문을 변형하는 경우(압축 방식 변경, 필드 재정렬 등)에는 정상적인 응답인데도 서명이 어긋납니다.

// 중간 계층이 본문을 건드리는 환경에서만
const cook = new ApiCook('project-id', {
    apiKey: 'apk_...',
    verifySignature: false,
});

이전 버전 문서에는 이 옵션의 기본값이 false로 적혀 있었습니다. 현재 SDK는 true입니다.

cdnBase와 proxyBase

기본값은 둘 다 https://api.apicook.dev입니다. proxyBase는 지정하지 않으면 cdnBase를 따라갑니다.

설정 JSON을 별도 CDN에서 서빙하도록 구성했다면 두 값이 달라져야 합니다. 이때 proxyBase를 함께 지정하지 않으면 프록시 호출이 CDN으로 가서 404를 받습니다.

const cook = new ApiCook('project-id', {
    apiKey: 'apk_...',
    cdnBase: 'https://cdn.example.com',        // 설정 JSON
    proxyBase: 'https://api.apicook.dev',      // 프록시 호출
});

환경변수 두는 곳

SDK 키를 코드에 문자열로 박지 마세요. 서버 환경이라면 환경변수가 정석입니다.

# .env
APICOOK_PROJECT_ID=...
APICOOK_API_KEY=apk_...

브라우저에서 쓴다면 사정이 다릅니다. NEXT_PUBLIC_ 같은 접두사가 붙은 변수는 번들에 그대로 들어가므로, 그 키는 공개된 것으로 취급해야 합니다. 프로젝트 설정의 허용 도메인으로 사용처를 제한하는 것이 함께 필요합니다. 보안에서 자세히 다룹니다.