Codelifter SDK — 프로그래매틱 추출 API
노드 환경에서 직접 DOM→코드 변환. CI 파이프라인, 서버 사이드, 자동화 워크플로우에 삽입하세요.
BYOK (Bring Your Own Key)
anthropicKey 옵션으로 자신의 Anthropic API 키를 사용합니다. 키는 절대 로그에 남기지 마세요. v1.0.4에서는 서버 키를 제공하지 않으므로 BYOK 전용입니다.
설치
npm 또는 pnpm으로 설치합니다.
설치
bash
npm install @codelifter/sdk
# or
pnpm add @codelifter/sdk기본 사용법
extract() 함수 하나로 URL에서 컴포넌트를 추출합니다.
전체 페이지 추출
typescript
import { extract } from '@codelifter/sdk';
// 시그니처: extract(url: string, options: ExtractOptions)
const result = await extract('https://example.com', {
surface: 'sdk', // 필수 — 다음 메이저에 type error
framework: 'react',
anthropicKey: process.env.ANTHROPIC_KEY, // BYOK
});
// 응답 (McpExtractResponse):
// - pipelineMode: 'extension' | 'headless-bundled' | 'headless-remote'
// - extractionResult: { html, css, computedStyles, fonts, assets, tier2? }
// - generatedFiles: { path, content }[] (adapter 등록 시만 채워짐)
// - meta: { durationMs, tokensUsed, modelUsed }
console.log(result.extractionResult.html);
console.log(result.generatedFiles);셀렉터 + 파일 출력
typescript
import { extract } from '@codelifter/sdk';
// CSS 셀렉터로 특정 요소만 추출
const result = await extract('https://stripe.com', {
surface: 'sdk',
selector: '.hero',
framework: 'react',
anthropicKey: process.env.ANTHROPIC_KEY,
});
// 파일 저장은 호출자가 직접 처리 (SDK 는 output 옵션 없음 — CLI 만)
import { writeFileSync } from 'fs';
for (const file of result.generatedFiles) {
writeFileSync(file.path, file.content);
}surface 파라미터 (v1.0.4)
v1.0.4에서 허용된 surface: extension / sdk / cli / mcp. vscode / figma / raycast / github-action은 BLOCKED — v1.0.5에서 지원 예정. 상위 통합이 자기 식별자를 forward할 수 있지만 v1.0.4에서는 BLOCKED 응답을 받습니다.
BLOCKED surface 예시
typescript
// ❌ v1.0.4에서 BLOCKED — v1.0.5에서 지원 예정
const result = await extract('https://example.com', {
surface: 'vscode', // BLOCKED: vscode | figma | raycast | github-action
anthropicKey: process.env.ANTHROPIC_KEY,
});
// → backend 403: SURFACE_BLOCKED
// { code: 'SURFACE_BLOCKED', surface: 'vscode',
// supportedSurfaces: ['extension', 'sdk', 'cli', 'mcp'] }
// ✅ v1.0.4 허용 surface
// extension | sdk | cli | mcpsurface 미명시 시 경고
surface를 생략하면 console.warn이 출력됩니다. 다음 메이저 버전에서 타입 에러로 격상될 예정입니다.
surface 생략 경고
typescript
// ⚠️ surface 생략 시 console.warn 발생
const result = await extract('https://example.com', {
// surface 없음
framework: 'react',
anthropicKey: process.env.ANTHROPIC_KEY,
});
// console.warn: [codelifter/sdk] Deprecated: options.surface 미지정.
// 다음 메이저 버전에서 surface 는 필수 파라미터가 됩니다.
// 직접 SDK 호출이면 { surface: 'sdk' } 를 명시하세요.CI/CD 통합
GitHub Actions
yaml
# GitHub Actions 예시
- name: Extract hero component
run: |
node -e "
const { extract } = require('@codelifter/sdk');
const { writeFileSync } = require('fs');
const result = await extract(process.env.TARGET_URL, {
surface: 'sdk',
selector: '.hero',
framework: 'react',
anthropicKey: process.env.ANTHROPIC_KEY,
});
for (const f of result.generatedFiles) writeFileSync(f.path, f.content);
"
env:
ANTHROPIC_KEY: ${{ secrets.ANTHROPIC_KEY }}
TARGET_URL: https://example.com옵션 참조
| 옵션 | 타입 | 설명 |
|---|---|---|
url | string | 추출 대상 URL (필수) |
surface | 'sdk' | 'cli' | ... | 진입점 식별자. v1.0.4 허용: 'extension' | 'sdk' | 'cli' | 'mcp' |
anthropicKey | string | Anthropic API 키 (BYOK, 필수). 절대 로그 X |
framework | 'react' | 'vue' | 'svelte' | 출력 프레임워크 (기본: react) |
selector | string | CSS 셀렉터 (없으면 전체 페이지) |
output | string | 출력 파일 경로 (선택) |
보안 주의사항
anthropicKey는 환경변수(process.env.ANTHROPIC_KEY)에서만 읽으세요. 코드에 하드코딩하거나 클라이언트에 노출하지 마세요.
- anthropicKey는 process.env에서만 읽기 — 코드에 하드코딩 금지
- 클라이언트 번들에 SDK를 포함하지 말 것 — Node.js 서버 전용
- .env 파일을 git에 커밋하지 말 것