@promstack-1/sdk

PromStack을 위한 공식 TypeScript/JavaScript SDK입니다.

설치

npm install @promstack-1/sdk
# 또는
yarn add @promstack-1/sdk
# 또는
pnpm add @promstack-1/sdk

빠른 시작

import { PromStackClient } from '@promstack-1/sdk';

// 클라이언트 초기화
const client = new PromptManagerClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://promstack.com'
});

// 프롬프트 목록 가져오기
const prompts = await client.getPrompts();
console.log(prompts);

// 특정 프롬프트 가져오기
const prompt = await client.getPrompt(1);
console.log(prompt.content);

// 변수 템플릿 렌더링
const rendered = client.renderPrompt(prompt.content, {
    name: '홍길동',
    topic: 'AI'
});

// 실행 기록 저장
const { id } = await client.recordRun({
    promptId: 1,
    response: 'AI가 생성한 응답...',
    provider: 'openai',
    variables: { name: '홍길동' }
});

API

PromptManagerClient

생성자

// 간단한 방식
const client = new PromptManagerClient('your-api-key');

// 전체 옵션
const client = new PromptManagerClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://api.example.com',  // 기본값: http://localhost:3000
    timeout: 30000,                       // 기본값: 30000ms
    retries: 3,                           // 기본값: 3
    retryDelay: 1000,                     // 기본값: 1000ms
    enableCache: true,                    // 기본값: false
    cacheTTL: 60000                       // 기본값: 60000ms
});

프롬프트 메서드

getPrompts(options?)

const prompts = await client.getPrompts({
    q: '검색어',           // 제목 검색
    tag: 'marketing',     // 태그 필터
    category: 'writing',  // 카테고리 필터
    limit: 10,            // 결과 수 제한
    offset: 0,            // 페이지네이션 오프셋
    sort: 'updated',      // 정렬 (created, updated, title, likes)
    order: 'desc'         // 정렬 방향 (asc, desc)
});

getPrompt(id) / getPromptVersion(id, version) / getPromptVersions(id)

const prompt = await client.getPrompt(1);
const promptV2 = await client.getPromptVersion(1, 2);
const versions = await client.getPromptVersions(1);

searchPrompts(query, options?)

const result = await client.searchPrompts('마케팅', { limit: 10 });
console.log(`총 ${result.total}개 중 ${result.prompts.length}개 반환`);

실행 기록 메서드

recordRun(input) / getRuns(options?) / batchRecordRuns(inputs)

// 단일 실행 기록
const { id } = await client.recordRun({
    promptId: 1,
    response: 'AI 응답',
    provider: 'openai',
    tokenUsage: { totalTokens: 100 }
});

// 실행 기록 조회
const runs = await client.getRuns({ promptId: 1, limit: 20 });

// 일괄 기록
const result = await client.batchRecordRuns([
    { promptId: 1, response: '응답 1' },
    { promptId: 2, response: '응답 2' }
]);
console.log(`성공: ${result.successful}, 실패: ${result.failed}`);

프로젝트 & 통계 메서드

getProject() / getStats() / getCategories() / getTags()

const project = await client.getProject();
const stats = await client.getStats();
console.log(`프롬프트: ${stats.promptCount}, 실행: ${stats.runCount}`);

const categories = await client.getCategories();
const tags = await client.getTags();

유틸리티 메서드

renderPrompt() / parseVariables() / validateVariables()

const template = '안녕하세요 {{name}}님';

// 변수 추출
const vars = client.parseVariables(template);  // ['name']

// 변수 유효성 검증
const isValid = client.validateVariables(template, { name: '홍길동' });  // true

// 렌더링
const rendered = client.renderPrompt(template, { name: '홍길동' });

createRunner(options) / executeAndRecord()

// 재사용 가능한 러너 생성
const runner = client.createRunner({
    provider: 'openai',
    executor: async (content, userInput) => {
        const response = await openai.chat.completions.create({
            model: 'gpt-4',
            messages: [{ role: 'user', content }]
        });
        return response.choices[0].message.content;
    }
});

// 간편하게 실행
const result = await runner(1, '질문', { name: '홍길동' });

캐시 제어

client.clearCache();           // 전체 캐시 삭제
client.invalidateCache(key);   // 특정 키 삭제

에러 처리

import { 
    PromptManagerError, 
    AuthenticationError, 
    NotFoundError,
    ValidationError,
    TimeoutError,
    RateLimitError 
} from '@promstack-1/sdk';

try {
    const prompt = await client.getPrompt(999);
} catch (error) {
    if (error instanceof AuthenticationError) {
        console.log('API 키가 유효하지 않습니다');
    } else if (error instanceof NotFoundError) {
        console.log('프롬프트를 찾을 수 없습니다');
    } else if (error instanceof ValidationError) {
        console.log('입력값이 올바르지 않습니다');
    } else if (error instanceof TimeoutError) {
        console.log('요청 시간이 초과되었습니다');
    } else if (error instanceof RateLimitError) {
        console.log(`요청 한도 초과. ${error.retryAfter}초 후 재시도`);
    }
}

타입

모든 타입은 패키지에서 export됩니다:

import type { 
    Prompt, 
    PromptVersion,
    Project, 
    Run, 
    RunInput,
    Category,
    Tag,
    SearchResult,
    BatchRunResult,
    GetPromptsOptions,
    GetRunsOptions,
    ClientOptions 
} from '@promstack-1/sdk';

지원 환경

• Node.js 18+
• 브라우저 (Fetch API 지원)
• Edge Runtime (Vercel, Cloudflare Workers)

라이선스

MIT