entity-server-client 0.3.2 → 1.0.1

package/docs/api/request.md

@@ -1,118 +0,0 @@
-# 범용 HTTP 요청
-
-`EntityServerClient`에서 제공하지 않는 커스텀 라우트(go서버·앱서버 신규 엔드포인트 등)를 직접 호출할 때 사용합니다.
-인증 헤더, 패킷 암호화, HMAC 서명 등은 기존 SDK 옵션 그대로 자동 적용됩니다.
-
----
-
-## `requestJson<T>(method, path, body?, withAuth?, extraHeaders?)`
-
-JSON 요청·응답의 범용 메서드입니다.
-
-- 응답이 `application/json`이면 파싱하여 반환합니다.
-- 응답이 `application/octet-stream`이면 패킷 복호화 후 반환합니다.
-- `ok` 필드 강제 없음 — go서버처럼 자유 응답 포맷을 그대로 반환합니다.
-- `encryptRequests: true`이면 요청 바디도 자동 암호화됩니다.
-
-| 파라미터       | 타입                     | 기본값 | 설명                      |
-| -------------- | ------------------------ | ------ | ------------------------- |
-| `method`       | `string`                 |        | `"GET"`, `"POST"` 등      |
-| `path`         | `string`                 |        | `/api/v1/...` 형태의 경로 |
-| `body`         | `unknown`                | —      | 요청 바디 (GET이면 생략)  |
-| `withAuth`     | `boolean`                | `true` | `Authorization` 헤더 포함 |
-| `extraHeaders` | `Record<string, string>` | —      | 추가 헤더                 |
-
-```ts
-// GET — 인증 없이
-const res = await client.requestJson<{ version: string }>(
-    "GET",
-    "/api/v1/status",
-    undefined,
-    false,
-);
-console.log(res.version);
-
-// POST — 인증 포함, 암호화 자동 적용
-const res = await client.requestJson<{ distance_nm: number }>(
-    "POST",
-    "/api/v1/distance-server/route",
-    { from: [37.5665, 126.978], to: [35.1796, 129.0756] },
-);
-console.log(res.distance_nm);
-
-// 추가 헤더
-const res = await client.requestJson<MyResponse>(
-    "POST",
-    "/api/v1/custom/endpoint",
-    { key: "value" },
-    true,
-    { "X-Custom-Header": "value" },
-);
-```
-
----
-
-## `requestBinary(method, path, body?, withAuth?)`
-
-바이너리(ArrayBuffer) 응답을 그대로 반환합니다.
-이미지, PDF, 압축 파일 등 바이너리 스트림이 오는 엔드포인트에 사용합니다.
-
-```ts
-const buffer = await client.requestBinary("GET", "/api/v1/export/report.pdf");
-
-// Blob 변환 후 다운로드
-const blob = new Blob([buffer], { type: "application/pdf" });
-const url = URL.createObjectURL(blob);
-```
-
----
-
-## `requestForm<T>(method, path, form, withAuth?)`
-
-`multipart/form-data` 요청을 보내고 JSON 응답을 반환합니다.
-파일과 일반 필드를 함께 전송해야 하는 커스텀 엔드포인트에 사용합니다.
-
-```ts
-const form = new FormData();
-form.append("file", fileBlob, "document.pdf");
-form.append("category", "report");
-
-const res = await client.requestForm<{ ok: boolean; seq: number }>(
-    "POST",
-    "/api/v1/custom/upload",
-    form,
-);
-console.log(res.seq);
-```
-
----
-
-## `requestFormBinary(method, path, form, withAuth?)`
-
-`multipart/form-data` 요청을 보내고 바이너리(ArrayBuffer)를 반환합니다.
-업로드 후 처리된 파일(변환·압축 등)을 바이너리로 받을 때 사용합니다.
-
-```ts
-const form = new FormData();
-form.append("image", imageBlob, "photo.jpg");
-
-const processedBuffer = await client.requestFormBinary(
-    "POST",
-    "/api/v1/custom/image-process",
-    form,
-);
-```
-
----
-
-## 내부 메서드와의 차이
-
-SDK 내부에서 엔티티 API를 호출할 때는 `ok: true` 강제 검사가 있는 `_request()`를 사용합니다.
-외부에서 커스텀 엔드포인트를 호출할 때는 위의 public 메서드를 사용하세요.
-
-| 메서드              | public | `ok` 강제 | 암호화 | 용도                          |
-| ------------------- | ------ | --------- | ------ | ----------------------------- |
-| `requestJson`       | ✅     | ❌        | ✅     | 커스텀 라우트 (JSON)          |
-| `requestBinary`     | ✅     | ❌        | ❌     | 커스텀 라우트 (바이너리)      |
-| `requestForm`       | ✅     | ✅        | ❌     | 커스텀 라우트 (form)          |
-| `requestFormBinary` | ✅     | ❌        | ❌     | 커스텀 라우트 (form→바이너리) |

package/docs/api/setup.md

@@ -1,43 +0,0 @@
-# 인스턴스 생성/설정
-
-## `new EntityServerClient(options?)`
-
-| 옵션               | 타입                               | 기본값                             | 설명                                                                                                                                                                                 |
-| ------------------ | ---------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `baseUrl`          | `string`                           | `VITE_ENTITY_SERVER_URL` 또는 `""` | 서버 주소                                                                                                                                                                            |
-| `token`            | `string`                           | `""`                               | JWT Access Token                                                                                                                                                                     |
-| `encryptRequests`  | `boolean`                          | `false`                            | `true` 로 설정하면 인증된 POST/PUT/PATCH 요청 바디를 XChaCha20-Poly1305 로 암호화하여 전송합니다. 서버에서 `requirePacketEncryption = true` 로 설정된 경우 반드시 활성화해야 합니다. |
-| `keepSession`      | `boolean`                          | `false`                            | `true`이면 `login()` 성공 후 Access Token 만료 전에 자동으로 갱신합니다.                                                                                                             |
-| `refreshBuffer`    | `number`                           | `60`                               | 만료 몇 초 전에 갱신을 시도할지 설정합니다. 예: `expires_in=3600`, `refreshBuffer=60` → 3540초 후 갱신                                                                               |
-| `onTokenRefreshed` | `(accessToken, expiresIn) => void` | —                                  | 자동 갱신 성공 시 호출됩니다. 새 `access_token`을 받아 앱 레벨 저장소에 업데이트하세요.                                                                                              |
-| `onSessionExpired` | `(error: Error) => void`           | —                                  | 세션 유지 갱신 실패 시 호출됩니다 (refresh_token 만료 등). 로그인 페이지로 이동하는 등의 처리를 여기서 합니다.                                                                       |
-
-```ts
-// 직접 생성
-const client = new EntityServerClient({
-    baseUrl: "https://api.example.com",
-    token: "eyJhbGciOi...",
-    encryptRequests: true, // 요청 바디 암호화 활성화
-});
-
-// 싱글톤 (환경변수 자동 읽기)
-import { entityServer } from "entity-server-client";
-```
-
-## `configure(options)`
-
-런타임에 설정을 갱신합니다.
-
-```ts
-client.configure({
-    baseUrl: "https://api.example.com",
-    token: "new-access-token",
-    encryptRequests: true,
-});
-```
-
-## `setToken(token)`
-
-```ts
-client.setToken("eyJhbGciOi...");
-```

package/docs/api/sms.md

@@ -1,45 +0,0 @@
-# SMS
-
-## `smsSend(req)`
-
-SMS를 직접 발송합니다.
-
-| 필드   | 타입     | 설명                               |
-| ------ | -------- | ---------------------------------- |
-| `to`   | `string` | 수신 전화번호 (`01012345678` 형식) |
-| `text` | `string` | 메시지 내용                        |
-| `from` | `string` | 발신 번호 (미지정 시 설정값 사용)  |
-
-```ts
-const res = await client.smsSend({
-    to: "01012345678",
-    text: "안녕하세요. 인증번호는 123456입니다.",
-});
-res.seq; // 발송 로그 seq
-```
-
-## `smsStatus(seq)`
-
-SMS 발송 처리 상태를 조회합니다.
-
-```ts
-const res = await client.smsStatus(10);
-res.status; // "sent" | "failed" | "pending"
-```
-
-## `smsVerificationSend(phone)`
-
-SMS 인증번호를 발송합니다. 인증 불필요 (공개 API).
-
-```ts
-await client.smsVerificationSend("01012345678");
-```
-
-## `smsVerificationVerify(phone, code)`
-
-발송된 SMS 인증번호를 검증합니다. 인증 불필요 (공개 API).
-
-```ts
-const res = await client.smsVerificationVerify("01012345678", "123456");
-res.verified; // true | false
-```

package/docs/api/smtp.md

@@ -1,33 +0,0 @@
-# SMTP 메일
-
-## `smtpSend(req)`
-
-SMTP를 통해 이메일을 발송합니다.
-
-| 필드      | 타입       | 설명                         |
-| --------- | ---------- | ---------------------------- |
-| `to`      | `string`   | 수신 이메일 주소             |
-| `subject` | `string`   | 이메일 제목                  |
-| `html`    | `string`   | HTML 본문                    |
-| `text`    | `string`   | 텍스트 본문 (HTML 대체)      |
-| `from`    | `string`   | 발신 주소 (미지정 시 설정값) |
-| `cc`      | `string[]` | 참조 수신자 목록             |
-| `bcc`     | `string[]` | 숨은 참조 수신자 목록        |
-
-```ts
-const res = await client.smtpSend({
-    to: "user@example.com",
-    subject: "가입을 환영합니다!",
-    html: "<h1>안녕하세요</h1><p>가입해주셔서 감사합니다.</p>",
-});
-res.seq; // 발송 로그 seq
-```
-
-## `smtpStatus(seq)`
-
-SMTP 발송 로그의 처리 상태를 조회합니다.
-
-```ts
-const res = await client.smtpStatus(5);
-res.status; // "sent" | "failed" | "pending"
-```

package/docs/api/transaction.md

@@ -1,50 +0,0 @@
-# 트랜잭션
-
-여러 submit/delete를 하나의 DB 트랜잭션으로 묶습니다.
-트랜잭션은 **5분 TTL**을 가집니다. 이 안에 commit 또는 rollback을 해야 합니다.
-
-```
-transStart → submit/delete (여러 개) → transCommit
-                                      └→ transRollback (실패 시)
-```
-
-## `transStart()`
-
-트랜잭션을 시작하고 내부 활성 트랜잭션 ID를 저장합니다.
-이후 `submit()`/`delete()`는 `X-Transaction-ID` 헤더를 자동 포함합니다.
-
-```ts
-const txId = await client.transStart();
-```
-
-## `transCommit(transactionId?)`
-
-큐에 쌓인 모든 작업을 단일 DB 트랜잭션으로 일괄 실행합니다.
-하나라도 실패하면 전체 ROLLBACK됩니다.
-
-```ts
-await client.transStart();
-await client.submit("order", { product_seq: 1, qty: 2 });
-await client.submit("inventory", { seq: 1, stock: 48 });
-const result = await client.transCommit();
-// result.results → [{ entity: "order", action: "submit", seq: 55 }, ...]
-```
-
-> **트랜잭션 중 submit 응답**: commit 전에는 `{ ok: true, queued: true, seq: "$tx.0" }` 형태의
-> placeholder가 반환됩니다. `$tx.0`, `$tx.1` 값은 commit 시 실제 seq로 자동 치환되므로
-> 후속 submit의 외래키 값으로 그대로 사용할 수 있습니다.
-
-## `transRollback(transactionId?)`
-
-- 아직 commit 전 (큐에 남아있음): 큐를 버립니다. DB에 아무 변경 없음.
-- 이미 commit 후: history 기반으로 전체 되돌립니다.
-
-```ts
-try {
-    await client.transStart();
-    await client.submit("order", { ... });
-    await client.transCommit();
-} catch (e) {
-    await client.transRollback(); // 활성 트랜잭션 자동 참조
-}
-```

package/docs/api/utils.md

@@ -1,52 +0,0 @@
-# QR코드 / 바코드
-
-## `qrcode(content, opts?)`
-
-QR 코드 PNG를 생성합니다. `ArrayBuffer`를 반환합니다.
-
-| 옵션     | 타입     | 설명                              |
-| -------- | -------- | --------------------------------- |
-| `size`   | `number` | 이미지 크기 (px). 기본값 `256`    |
-| `level`  | `string` | 오류 정정 레벨 `L \| M \| Q \| H` |
-| `format` | `string` | 출력 포맷. 기본값 `"png"`         |
-
-```ts
-const buf = await client.qrcode("https://example.com", { size: 300 });
-const blob = new Blob([buf], { type: "image/png" });
-img.src = URL.createObjectURL(blob);
-```
-
-## `qrcodeBase64(content, opts?)`
-
-QR 코드를 base64 / data URI JSON으로 반환합니다.
-
-```ts
-const res = await client.qrcodeBase64("https://example.com");
-res.data_uri; // "data:image/png;base64,..."
-res.data; // base64 문자열
-img.src = res.data_uri;
-```
-
-## `qrcodeText(content, opts?)`
-
-QR 코드를 ASCII 아트 텍스트로 반환합니다.
-
-```ts
-const res = await client.qrcodeText("https://example.com");
-console.log(res.text); // ASCII 아트 QR 코드
-```
-
-## `barcode(content, opts?)`
-
-바코드 PNG를 생성합니다. `ArrayBuffer`를 반환합니다.
-
-| 옵션   | 타입     | 설명                                               |
-| ------ | -------- | -------------------------------------------------- |
-| `type` | `string` | 바코드 형식. 예: `"code128"`, `"ean13"`, `"qr"` 등 |
-| `size` | `number` | 이미지 크기                                        |
-
-```ts
-const buf = await client.barcode("1234567890128", { type: "ean13" });
-const blob = new Blob([buf], { type: "image/png" });
-img.src = URL.createObjectURL(blob);
-```

package/docs/apis.md

@@ -1,26 +0,0 @@
-# entity-server-client API 문서
-
-각 섹션은 별도 파일로 분리되어 있습니다.
-
-## 목차
-
-| 구분               | 파일                                     |
-| ------------------ | ---------------------------------------- |
-| import             | [api/import.md](api/import.md)           |
-| 서버 헬스체크      | [api/health.md](api/health.md)           |
-| 인스턴스 생성/설정 | [api/setup.md](api/setup.md)             |
-| 인증               | [api/auth.md](api/auth.md)               |
-| 트랜잭션           | [api/transaction.md](api/transaction.md) |
-| 엔티티 CRUD / 조회 | [api/entity.md](api/entity.md)           |
-| 푸시 관련          | [api/push.md](api/push.md)               |
-| 이메일 인증 / 변경 | [api/email.md](api/email.md)             |
-| SMS                | [api/sms.md](api/sms.md)                 |
-| SMTP 메일          | [api/smtp.md](api/smtp.md)               |
-| 알림톡 / 친구톡    | [api/alimtalk.md](api/alimtalk.md)       |
-| PG 결제            | [api/pg.md](api/pg.md)                   |
-| 파일 스토리지      | [api/file.md](api/file.md)               |
-| 본인인증           | [api/identity.md](api/identity.md)       |
-| QR코드 / 바코드    | [api/utils.md](api/utils.md)             |
-| React Hook         | [api/react.md](api/react.md)             |
-| 범용 HTTP 요청     | [api/request.md](api/request.md)         |
-| 암호화 패킷 처리   | [api/packet.md](api/packet.md)           |

package/docs/react.md

@@ -1,137 +0,0 @@
-# React 전용 가이드
-
-## import
-
-```ts
-import { useEntityServer } from "entity-server-client/react";
-```
-
-## 기본 사용
-
-```ts
-import { useEntityServer } from "entity-server-client/react";
-
-export function AccountPage() {
-  const { client } = useEntityServer({
-    tokenResolver: () => localStorage.getItem("auth_access_token"),
-  });
-
-  // 예: 버튼 클릭 시 목록 조회
-  const onClick = async () => {
-    const res = await client.list("account", { page: 1, limit: 20 });
-    console.log(res.data);
-  };
-
-  return <button onClick={onClick}>불러오기</button>;
-}
-```
-
-## `client`로 사용 가능한 모든 API
-
-`client`는 `EntityServerClient` 인스턴스 그대로이므로 엔티티 CRUD 외에도 **모든 API**를 호출할 수 있습니다.  
-`submit` / `del` / `query` 래퍼는 `isPending` / `error` 상태를 자동 관리해주는 편의 메서드일 뿐입니다.
-
-```tsx
-const { client, submit, del } = useEntityServer({
-    tokenResolver: () => localStorage.getItem("auth_access_token"),
-});
-
-// 인증
-await client.login("hong@example.com", "pw");
-await client.logout();
-
-// 트랜잭션
-await client.transStart();
-await client.submit("order", { product_seq: 1, qty: 2 });
-await client.transCommit();
-
-// 파일 업로드
-const res = await client.fileUpload("product", file, { refSeq: 10 });
-
-// SMS 인증
-await client.smsVerificationSend("01012345678");
-await client.smsVerificationVerify("01012345678", "123456");
-
-// 알림톡 발송
-await client.alimtalkSend({
-    to: "01012345678",
-    templateCode: "ORDER_CONFIRM",
-    variables: {},
-});
-
-// PG 결제
-const order = await client.pgCreateOrder({
-    orderId: "ord-001",
-    amount: 15000,
-    orderName: "상품 A",
-    customerName: "홍길동",
-    customerEmail: "hong@example.com",
-});
-await client.pgConfirmPayment({
-    paymentKey: "key",
-    orderId: "ord-001",
-    amount: 15000,
-});
-
-// 본인인증
-const req = await client.identityRequest({
-    redirect_url: "https://example.com/callback",
-});
-
-// QR코드
-const buf = await client.qrcode("https://example.com", { size: 300 });
-```
-
-카테고리별 상세 파라미터는 [api/](api/) 폴더의 각 문서를 참고하세요.
-
-## 옵션
-
-### `singleton` (기본: `true`)
-
-- `true`: 패키지 전역 인스턴스(`entityServer`)를 사용
-- `false`: 훅 호출 스코프마다 새 인스턴스 생성
-
-```ts
-const { client } = useEntityServer({
-    singleton: false,
-    baseUrl: "http://localhost:47200",
-});
-```
-
-### `tokenResolver`
-
-렌더 시점에 토큰을 읽어 자동으로 `setToken`을 적용합니다.
-
-```ts
-const { client } = useEntityServer({
-    tokenResolver: () => sessionStorage.getItem("access_token"),
-});
-```
-
-### `baseUrl`, `token`
-
-`EntityServerClientOptions`와 동일하게 전달할 수 있습니다.
-
-```ts
-const { client } = useEntityServer({
-    baseUrl: import.meta.env.VITE_ENTITY_SERVER_URL,
-});
-```
-
-## React Query와 함께 사용 예시
-
-```ts
-import { useQuery } from "@tanstack/react-query";
-import { useEntityServer } from "entity-server-client/react";
-
-export function useAccountList() {
-    const { client } = useEntityServer({
-        tokenResolver: () => localStorage.getItem("auth_access_token"),
-    });
-
-    return useQuery({
-        queryKey: ["account", "list"],
-        queryFn: () => client.list("account", { page: 1, limit: 20 }),
-    });
-}
-```

package/src/EntityServerClient.ts

@@ -1,28 +0,0 @@
-/**
- * @file EntityServerClient.ts
- * Mixin 패턴으로 구성된 EntityServerClient.
- *
- * 절(section)별 구현:
- *   src/client/base.ts      — 상태·생성자·공통 헬퍼
- *   src/mixins/auth.ts      — 인증 (로그인/로그아웃/me/트랜잭션 등)
- *   src/mixins/entity.ts    — 트랜잭션 & 엔티티 CRUD
- *   src/mixins/push.ts      — 푸시 디바이스 관리
- *   src/mixins/smtp.ts      — SMTP 메일 발송
- *   src/mixins/file.ts      — 파일 스토리지
- *   src/mixins/utils.ts     — QR코드/바코드/PDF변환
- */
-import { EntityServerClientBase } from "./client/base";
-import { AuthMixin } from "./mixins/auth";
-import { EntityMixin } from "./mixins/entity";
-import { PushMixin } from "./mixins/push";
-import { SmtpMixin } from "./mixins/smtp";
-import { FileMixin } from "./mixins/file";
-import { UtilsMixin } from "./mixins/utils";
-
-// ─── Composed class ───────────────────────────────────────────────────────────
-
-export class EntityServerClient extends UtilsMixin(
-    FileMixin(
-        SmtpMixin(PushMixin(EntityMixin(AuthMixin(EntityServerClientBase)))),
-    ),
-) {}