entity-server-client 0.2.5 → 0.3.0

package/docs/api/react.md

@@ -0,0 +1,141 @@
+# React Hook
+
+## `useEntityServer(options?)`
+
+React 컴포넌트에서 EntityServerClient를 사용할 때 권장되는 훅입니다.
+`submit` / `del` / `query` 의 `isPending`, `error` 상태를 자동으로 관리합니다.
+
+```ts
+import { useEntityServer } from "entity-server-client/react";
+```
+
+### 옵션
+
+| 옵션               | 타입                                | 기본값 | 설명                                                                                            |
+| ------------------ | ----------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
+| `singleton`        | `boolean`                           | `true` | `true`이면 전역 `entityServer` 인스턴스 사용                                                    |
+| `baseUrl`          | `string`                            | —      | 서버 주소 (singleton일 때 `configure()` 호출)                                                   |
+| `token`            | `string`                            | —      | JWT Access Token                                                                                |
+| `tokenResolver`    | `() => string \| undefined \| null` | —      | 렌더 시점에 토큰을 동적으로 주입하는 함수                                                       |
+| `keepSession`      | `boolean`                           | —      | 세션 유지 활성화                                                                                |
+| `onTokenRefreshed` | `(accessToken, expiresIn) => void`  | —      | 세션 유지 성공 콜백                                                                             |
+| `onSessionExpired` | `(error: Error) => void`            | —      | 세션 만료 콜백 (refresh_token 만료 등)                                                          |
+| `resumeSession`    | `string`                            | —      | 저장된 refresh_token. 마운트 시 `refreshToken()` 호출해 토큰 복원 + `keepSession` 타이머 재시작 |
+
+### 반환값
+
+| 필드        | 타입                 | 설명                                                  |
+| ----------- | -------------------- | ----------------------------------------------------- |
+| `client`    | `EntityServerClient` | **모든 API 메서드에 접근 가능한 클라이언트 인스턴스** |
+| `isPending` | `boolean`            | `submit` / `del` / `query` 진행 중 여부               |
+| `error`     | `Error \| null`      | 마지막 mutation 에러. 성공 또는 `reset()` 시 `null`   |
+| `reset`     | `() => void`         | `isPending`, `error` 초기화                           |
+| `submit`    | function             | `client.submit()` 래퍼 — 상태 자동 관리               |
+| `del`       | function             | `client.delete()` 래퍼 — 상태 자동 관리               |
+| `query`     | function             | `client.query()` 래퍼 — 상태 자동 관리                |
+
+> **`client`는 `EntityServerClient` 인스턴스 그대로입니다.**  
+> `submit` / `del` / `query` 래퍼는 `isPending` / `error` 상태를 자동 관리해주는 편의 메서드일 뿐이며,  
+> 인증, 푸시, 파일, SMS, PG 등 **모든 API**는 `client.메서드명()`으로 직접 호출합니다.
+
+### `client`로 사용 가능한 모든 API
+
+`client`를 통해 아래 모든 섹션의 메서드를 그대로 사용할 수 있습니다.
+
+| 카테고리           | 주요 메서드 (예시)                                                                 | 상세 문서                        |
+| ------------------ | ---------------------------------------------------------------------------------- | -------------------------------- |
+| 인증               | `login`, `logout`, `register`, `refreshToken`, `oauthLogin`, `enable2FA` …         | [auth.md](auth.md)               |
+| 트랜잭션           | `transStart`, `transCommit`, `transRollback`                                       | [transaction.md](transaction.md) |
+| 엔티티 CRUD / 조회 | `get`, `find`, `list`, `count`, `query`, `submit`, `delete`, `history`, `rollback` | [entity.md](entity.md)           |
+| 푸시               | `pushSend`, `pushSendAll`, `pushStatus`, `registerPushDevice` …                    | [push.md](push.md)               |
+| 이메일 인증        | `emailVerificationSend`, `emailVerificationConfirm`, `emailChange`                 | [email.md](email.md)             |
+| SMS                | `smsSend`, `smsVerificationSend`, `smsVerificationVerify`                          | [sms.md](sms.md)                 |
+| SMTP 메일          | `smtpSend`, `smtpStatus`                                                           | [smtp.md](smtp.md)               |
+| 알림톡 / 친구톡    | `alimtalkSend`, `alimtalkTemplates`, `friendtalkSend`                              | [alimtalk.md](alimtalk.md)       |
+| PG 결제            | `pgCreateOrder`, `pgConfirmPayment`, `pgCancelPayment`, `pgConfig`                 | [pg.md](pg.md)                   |
+| 파일 스토리지      | `fileUpload`, `fileDownload`, `fileDelete`, `fileList`, `fileToken`, `fileUrl`     | [file.md](file.md)               |
+| 본인인증           | `identityRequest`, `identityResult`, `identityVerifyCI`                            | [identity.md](identity.md)       |
+| QR코드 / 바코드    | `qrcode`, `qrcodeBase64`, `barcode`                                                | [utils.md](utils.md)             |
+
+### 기본 사용 예시
+
+```tsx
+import { useEntityServer } from "entity-server-client/react";
+
+function AccountForm() {
+    const { submit, del, isPending, error, reset } = useEntityServer();
+
+    const handleSave = async () => {
+        reset();
+        await submit("account", { name: "홍길동", email: "hong@example.com" });
+    };
+
+    const handleDelete = async (seq: number) => {
+        await del("account", seq);
+    };
+
+    return (
+        <div>
+            {isPending && <span>저장 중...</span>}
+            {error && <span style={{ color: "red" }}>{error.message}</span>}
+            <button onClick={handleSave} disabled={isPending}>
+                저장
+            </button>
+            <button onClick={() => handleDelete(1)} disabled={isPending}>
+                삭제
+            </button>
+        </div>
+    );
+}
+```
+
+### 동적 토큰 주입
+
+```tsx
+const { submit } = useEntityServer({
+    tokenResolver: () => localStorage.getItem("access_token"),
+});
+```
+
+### 페이지 새로고침 후 세션 복원
+
+`resumeSession`에 저장된 refresh_token을 넘기면 마운트 시 `refreshToken()`을 호출해
+새 access_token을 발급받고, `keepSession: true`이면 타이머도 자동 재시작됩니다.
+
+```tsx
+// App.tsx 또는 로그인 복원을 담당하는 컴포넌트
+export function AppShell() {
+    const storedRefreshToken =
+        localStorage.getItem("auth_refresh_token") ?? undefined;
+
+    useEntityServer({
+        resumeSession: storedRefreshToken,
+        keepSession: true,
+        onTokenRefreshed: (accessToken) => {
+            localStorage.setItem("auth_access_token", accessToken);
+        },
+        onSessionExpired: () => {
+            window.location.href = "/login";
+        },
+    });
+
+    return <RouterOutlet />;
+}
+```
+
+마운트 시 `resumeSession`이 있으면:
+
+1. `refreshToken(storedRefreshToken)` 호출 → 서버에서 새 access_token 발급
+2. 패키지 내부 `this.token` 자동 교체
+3. `onTokenRefreshed` 콜백 호출
+4. `keepSession: true`이면 다음 만료 전 타이머 자동 예약
+5. 실패 시 `onSessionExpired` 콜백 호출
+
+### 컴포넌트별 독립 인스턴스
+
+```tsx
+const { client } = useEntityServer({
+    singleton: false,
+    baseUrl: "https://other-server.example.com",
+});
+```

package/docs/api/setup.md

@@ -0,0 +1,43 @@
+# 인스턴스 생성/설정
+
+## `new EntityServerClient(options?)`
+
+| 옵션               | 타입                               | 기본값                                                 | 설명                                                                                                                                                                                 |
+| ------------------ | ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `baseUrl`          | `string`                           | `VITE_ENTITY_SERVER_URL` 또는 `http://localhost:47200` | 서버 주소                                                                                                                                                                            |
+| `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

@@ -0,0 +1,45 @@
+# 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

@@ -0,0 +1,33 @@
+# 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

@@ -0,0 +1,50 @@
+# 트랜잭션
+
+여러 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

@@ -0,0 +1,52 @@
+# 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);
+```