tago-native-ocr

영수증 OCR 툴킷 — 촬영 → OpenAI Vision 파싱(서버) → 검수. 웹/네이티브(Capacitor) 캡처 어댑터를 분리해 동일한 React 훅으로 양쪽에서 재사용합니다.

OpenAI 키는 클라이언트에 노출하지 않습니다. 파싱은 서버 엔드포인트가 OpenAI Vision을 호출하고, 이 패키지는 그 엔드포인트를 호출·검수하는 클라이언트입니다.

설치

npm install tago-native-ocr

react는 peer dependency입니다 (React 훅/컴포넌트 사용 시).

빠른 시작 (웹)

import { createOcrClient, useReceiptOcr } from 'tago-native-ocr';

const ocrClient = createOcrClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
  getToken: () => useAuthStore.getState().accessToken,
});

function ReceiptButton() {
  const { status, result, previewUrl, image, scan, reset, retry, error } =
    useReceiptOcr({ client: ocrClient });

  return (
    <>
      <button onClick={scan} disabled={status === 'uploading'}>
        영수증 촬영
      </button>
      {status === 'uploading' && <p>분석 중…</p>}
      {status === 'review' && result && (
        <pre>{JSON.stringify(result, null, 2)}</pre>
      )}
      {status === 'error' && <p>{error} <button onClick={retry}>재시도</button></p>}
    </>
  );
}

서버 엔드포인트 계약

POST {baseUrl}/api/v1/ocr/receipt (multipart, 필드명 image)

응답 (ApiResponse<ReceiptData> 기본 언래핑):

{
  "data": {
    "merchantName": "...", "expenseDate": "2026-06-04",
    "totalAmount": 12000, "currency": "KRW", "taxAmount": 1090,
    "category": "MEAL", "paymentMethod": "CARD",
    "lineItems": [{ "name": "아메리카노", "quantity": 2, "unitPrice": 4500, "amount": 9000 }],
    "confidence": 0.92, "rawText": "...", "amountMismatch": false
  }
}

unwrap 옵션으로 다른 응답 형태도 지원합니다.

네이티브(Capacitor) 캡처

import { createNativeCaptureProvider, base64ToBlob, useReceiptOcr } from 'tago-native-ocr';
import { Camera, CameraResultType, CameraSource } from '@capacitor/camera';

const nativeProvider = createNativeCaptureProvider(async () => {
  const photo = await Camera.getPhoto({
    resultType: CameraResultType.Base64,
    source: CameraSource.Camera,
  });
  const blob = base64ToBlob(photo.base64String!, 'image/jpeg');
  return { blob, previewUrl: `data:image/jpeg;base64,${photo.base64String}` };
});

useReceiptOcr({ client: ocrClient, captureProvider: nativeProvider });

API

| export | 설명 | |---|---| | createOcrClient(config) | OCR API 클라이언트 | | useReceiptOcr(options) | 촬영→파싱→검수 상태머신 훅 | | createWebCaptureProvider(opts) | 웹 파일/카메라 캡처 | | createNativeCaptureProvider(fn) | 네이티브 캡처 어댑터 | | base64ToBlob(b64, mime) | base64 → Blob 유틸 |

라이선스

MIT