@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

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

Quick Start

1. Provider 설정

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 폼 작성

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. 팝업 형태로 사용

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 사용법

템플릿 조회

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 생성

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 클라이언트를 직접 사용할 수도 있습니다.

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 타입을 제공합니다.

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

인증

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

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

스타일 커스터마이징

SDK는 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
• Issue Tracker