npm package: @scryn/scryn-ade-sdk
Description: Scryn ADE SDK - React components and API client for automated PDF form-filling service
Author: SANDBURG-inc R&D
Latest version: 0.1.0

# @scryn/scryn-ade-sdk

Scryn ADE (Auto-Document Entry) 서비스를 위한 React SDK입니다. **PDF 양식 폼 작성 및 생성** 기능을 React/Next.js 애플리케이션에 쉽게 통합할 수 있습니다.

## Features

- **React 19** 및 **Next.js 16** 지원
- PDF 폼 작성 UI 컴포넌트
- ADE Enum을 통한 자동 데이터 매핑
- PDF 자동 생성 및 다운로드
- 팝업/모달 형태로 사용 가능
- TypeScript 완전 지원

## Installation

```bash
npm install @scryn/scryn-ade-sdk
# 또는
pnpm add @scryn/scryn-ade-sdk
# 또는
yarn add @scryn/scryn-ade-sdk
```

## Quick Start

### 1. Provider 설정

```tsx
import { ScrynAdeProvider } from '@scryn/scryn-ade-sdk'
import '@scryn/scryn-ade-sdk/styles.css'

function App() {
  return (
    <ScrynAdeProvider
      config={{
        baseUrl: 'https://api.your-server.com',
        adminSecret: 'your-admin-secret', // X-ADMIN-SECRET 헤더 값
      }}
    >
      <YourApp />
    </ScrynAdeProvider>
  )
}
```

### 2. PDF 폼 작성

```tsx
import { PdfFormFiller } from '@scryn/scryn-ade-sdk'

function FormPage() {
  return (
    <PdfFormFiller
      templateId="template-123"
      initialValues={{ 'field-1': '홍길동' }}
      adeBindings={{ NAME_ME: '홍길동', PHONE_ME: '010-1234-5678' }}
      onSubmit={(result) => {
        console.log('PDF 생성 완료:', result.url)
        window.open(result.url, '_blank')
      }}
    />
  )
}
```

### 3. 팝업 형태로 사용

```tsx
import { ScrynAdePopup, usePopup, PdfFormFiller } from '@scryn/scryn-ade-sdk'

function FormButton() {
  const { isOpen, open, close, result } = usePopup()

  return (
    <>
      <button onClick={open}>양식 작성</button>

      <ScrynAdePopup
        isOpen={isOpen}
        onClose={close}
        options={{
          title: 'PDF 양식 작성',
          width: 900,
          height: 700,
        }}
      >
        <PdfFormFiller
          templateId="template-123"
          adeBindings={{ NAME_ME: '홍길동' }}
          onSubmit={(pdf) => close({ success: true, data: pdf })}
        />
      </ScrynAdePopup>

      {result?.success && (
        <a href={result.data.url} target="_blank">
          PDF 다운로드
        </a>
      )}
    </>
  )
}
```

## Hooks 사용법

### 템플릿 조회

```tsx
import { useTemplate } from '@scryn/scryn-ade-sdk'

function MyComponent() {
  const { template, loading, error, refetch } = useTemplate('template-id')

  if (loading) return <div>로딩 중...</div>
  if (error) return <div>에러: {error.message}</div>

  return <div>{template?.name}</div>
}
```

### PDF 생성

```tsx
import { useRenderTemplate, useQuickRender } from '@scryn/scryn-ade-sdk'

function MyComponent() {
  // 상세 옵션 사용
  const { renderTemplate, isRendering, result } = useRenderTemplate()

  const handleGenerate = async () => {
    const pdf = await renderTemplate('template-id', {
      fieldValues: { 'field-1': '값' },
      adeBindings: { NAME_ME: '홍길동' },
      options: { flatten: true },
    })
    window.open(pdf.url)
  }

  // 간편 생성
  const { quickRender, pdfUrl } = useQuickRender()

  const handleQuickGenerate = async () => {
    const url = await quickRender('template-id', {
      'field-1': '값',
    })
    window.open(url)
  }
}
```

## API Client 직접 사용

Provider 없이 API 클라이언트를 직접 사용할 수도 있습니다.

```tsx
import { initializeScrynAde, getScrynAdeClient } from '@scryn/scryn-ade-sdk'

// 초기화 (앱 시작 시 한 번)
initializeScrynAde({
  baseUrl: 'https://api.your-server.com',
  adminSecret: 'your-admin-secret',
})

// 어디서든 클라이언트 사용
const client = getScrynAdeClient()

// 템플릿 조회
const template = await client.getTemplate('template-id')

// PDF 생성
const result = await client.renderTemplate('template-id', {
  fieldValues: { 'field-1': '값' },
  adeBindings: { NAME_ME: '홍길동' },
})
```

## TypeScript Types

SDK는 완전한 TypeScript 타입을 제공합니다.

```tsx
import type {
  Template,
  TemplateField,
  FieldType,
  RenderTemplateDto,
  RenderTemplateResponse,
  ScrynAdeConfig,
} from '@scryn/scryn-ade-sdk'
```

## 인증

SDK는 `X-Admin-Secret` 헤더를 통한 인증을 사용합니다. `config.adminSecret`에 설정된 값이 모든 API 요청에 자동으로 포함됩니다.

```tsx
<ScrynAdeProvider
  config={{
    baseUrl: 'https://api.your-server.com',
    adminSecret: process.env.NEXT_PUBLIC_ADMIN_SECRET!,
  }}
>
```

## 스타일 커스터마이징

SDK는 CSS 변수를 사용하여 스타일을 정의합니다. 원하는 경우 변수를 오버라이드할 수 있습니다.

```css
:root {
  --scryn-primary: #3b82f6;
  --scryn-primary-hover: #2563eb;
  --scryn-border: #e5e7eb;
  /* ... */
}
```

## Requirements

- React >= 19.0.0
- React DOM >= 19.0.0
- Node.js >= 20.9.0

## License

MIT

## Links

- [Scryn ADE Backend API Documentation](./API-DOCS.md)
- [Issue Tracker](https://github.com/scryn/scryn-ade-sdk/issues)