entity-server-client 0.3.2 → 1.0.1

package/docs/api/alimtalk.md

@@ -1,62 +0,0 @@
-# 알림톡 / 친구톡
-
-카카오 비즈메시지(알림톡/친구톡)를 발송합니다.
-
-## `alimtalkSend(req)`
-
-카카오 알림톡을 발송합니다. 사전 승인된 템플릿을 사용합니다.
-
-| 필드           | 타입     | 설명                      |
-| -------------- | -------- | ------------------------- |
-| `to`           | `string` | 수신 전화번호             |
-| `templateCode` | `string` | 승인된 알림톡 템플릿 코드 |
-| `variables`    | `object` | 템플릿 변수 (키-값 맵)    |
-
-```ts
-const res = await client.alimtalkSend({
-    to: "01012345678",
-    templateCode: "ORDER_CONFIRM",
-    variables: {
-        orderId: "20260201-001",
-        totalAmount: "50,000",
-    },
-});
-res.seq; // 발송 로그 seq
-```
-
-## `alimtalkStatus(seq)`
-
-알림톡 발송 처리 상태를 조회합니다.
-
-```ts
-const res = await client.alimtalkStatus(7);
-res.status; // "sent" | "failed" | "pending"
-```
-
-## `alimtalkTemplates()`
-
-등록된 알림톡 템플릿 목록을 조회합니다.
-
-```ts
-const res = await client.alimtalkTemplates();
-res.items; // 템플릿 배열 [{ code, name, content, ... }]
-```
-
-## `friendtalkSend(req)`
-
-카카오 친구톡을 발송합니다. 승인된 채널 친구에게만 발송 가능합니다.
-
-| 필드      | 타입     | 설명                                 |
-| --------- | -------- | ------------------------------------ |
-| `to`      | `string` | 수신 전화번호                        |
-| `type`    | `string` | 메시지 타입 (`"text"`, `"image"` 등) |
-| `content` | `string` | 메시지 본문                          |
-
-```ts
-const res = await client.friendtalkSend({
-    to: "01012345678",
-    type: "text",
-    content: "안녕하세요! 신상품이 입고되었습니다.",
-});
-res.seq; // 발송 로그 seq
-```

package/docs/api/auth.md

@@ -1,256 +0,0 @@
-# 인증
-
-## `login(email, password)`
-
-이메일 + 비밀번호로 로그인합니다. 성공 시 내부 토큰이 자동으로 설정됩니다.
-
-```ts
-const auth = await client.login("admin@example.com", "password");
-// auth.access_token   — 이후 요청에 자동 사용됨
-// auth.refresh_token  — 만료 후 재발급에 사용
-// auth.expires_in     — 만료까지 남은 초
-```
-
-## `refreshToken(refreshToken)`
-
-Refresh Token으로 Access Token을 재발급받습니다.
-앱이 명시적으로 호출해야 하며, 성공하면 내부 `this.token`을 새 Access Token으로 교체합니다.
-
-> **패키지는 401을 감지해 자동으로 `refreshToken()`을 호출하지 않습니다.**
-> 401 발생 시 앱이 직접 catch해서 호출해야 합니다.
-
-```ts
-const result = await client.refreshToken(auth.refresh_token);
-// 성공 → this.token이 result.access_token으로 교체됨
-// result.access_token
-// result.expires_in
-```
-
-## `logout(refreshToken)`
-
-서버에 로그아웃을 요청하고 내부 토큰을 초기화합니다.
-Refresh Token을 서버에 전달해 무효화하므로 해당 토큰으로 더 이상 재발급이 불가능합니다.
-Refresh Token이 이미 만료된 경우에도 서버는 성공으로 응답합니다.
-
-```ts
-await client.logout(auth.refresh_token);
-// 이후 client 내부 token = "" 으로 초기화됨
-```
-
-## 토큰 만료 처리
-
-**패키지가 자동으로 처리하는 것:**
-
-| 동작                  | 내부 토큰 갱신 |
-| --------------------- | -------------- |
-| `login()` 성공        | ✅ 자동 세팅   |
-| `refreshToken()` 성공 | ✅ 자동 교체   |
-| `logout()` 호출       | ✅ `""` 초기화 |
-
-**패키지가 처리하지 않는 것:**
-
-- **401 자동 재시도 없음**: access_token이 만료되어 서버가 401을 반환하면 패키지는 에러를 throw합니다. 앱이 직접 잡아서 `refreshToken()`을 호출하고 재시도해야 합니다.
-- **토큰 영속성 없음**: 페이지 새로고침 시 싱글톤 인스턴스가 초기화되어 내부 token이 `""` 로 리셋됩니다. 앱이 직접 복원 후 `setToken()` 또는 `configure({ token })` 으로 재세팅해야 합니다.
-
-**401 발생 후 앱의 처리 흐름:**
-
-```
-API 요청 → 401 응답 → entityServer.refreshToken(refresh_token) 호출
-                              ↓ 성공              ↓ 실패 (refresh_token도 만료)
-               setToken(new_access_token)      로그인 페이지로 이동
-               원래 요청 재시도
-```
-
-**주의:** `refreshToken()`이 성공해 패키지 내부 토큰이 교체되더라도, 앱 내 다른 HTTP 클라이언트(axios 등)에는 별도로 토큰을 전달해야 합니다.
-
-## `keepSession` — 세션 유지 (Silent Refresh)
-
-`keepSession: true` 옵션 설정 시, `login()` 성공 후 만료 `refreshBuffer`초 전에 패키지 내부 타이머가 자동으로 `refreshToken()`을 호출합니다.
-갱신이 성공하면 타이머를 다시 예약해 로그인 상태를 계속 유지합니다.
-`logout()` 또는 `stopKeepSession()` 호출 시 타이머가 정리됩니다.
-
-```ts
-entityServer.configure({
-    keepSession: true,
-    refreshBuffer: 60, // 만료 60초 전에 갱신 (기본값)
-    onTokenRefreshed: (accessToken, expiresIn) => {
-        // 갱신 성공 — 앱 레벨 저장소 업데이트
-        localStorage.setItem("auth_access_token", accessToken);
-    },
-    onSessionExpired: (error) => {
-        // refresh_token 만료 등으로 갱신 실패
-        console.error("세션 만료:", error);
-        window.location.href = "/login";
-    },
-});
-
-// 이후 login() 하면 타이머 자동 시작
-const auth = await entityServer.login(email, password);
-// expires_in=3600이면 3540초 후 자동 갱신, 이후 반복
-```
-
-**수동으로 타이머 중지:**
-
-```ts
-entityServer.stopKeepSession();
-```
-
-> **페이지 새로고침 시**: 타이머는 메모리에만 존재하므로 새로고침 시 초기화됩니다.
-> `useEntityServer`의 `resumeSession` 옵션을 사용하면 페이지 새로고침 후에도 세션을 자동으로 복원할 수 있습니다.
-
-## OAuth 연동
-
-### `oauthLink(provider, code, state?)`
-
-OAuth 프로바이더를 현재 계정에 연동합니다.
-
-```ts
-await client.oauthLink("google", "auth-code-from-callback");
-```
-
-### `oauthUnlink(provider)`
-
-OAuth 프로바이더 연동을 해제합니다.
-
-```ts
-await client.oauthUnlink("google");
-```
-
-### `oauthProviders()`
-
-현재 계정에 연동된 OAuth 프로바이더 목록을 반환합니다.
-
-```ts
-const res = await client.oauthProviders();
-res.data; // [{ provider: "google", email: "...", linked_at: "..." }]
-```
-
-### `oauthTokenRefresh(provider)`
-
-특정 OAuth 프로바이더의 액세스 토큰을 갱신합니다.
-
-```ts
-const res = await client.oauthTokenRefresh("google");
-res.access_token;
-```
-
-## 2단계 인증 (2FA)
-
-### `twoFactorSetup()`
-
-2FA 설정을 시작하고 QR 코드 / 시크릿을 반환합니다.
-
-```ts
-const res = await client.twoFactorSetup();
-res.qr_url; // QR 코드 URL
-res.secret; // TOTP 시크릿
-res.setup_token;
-```
-
-### `twoFactorSetupVerify(code, setupToken)`
-
-TOTP 코드로 2FA 설정을 완료합니다.
-
-```ts
-const res = await client.twoFactorSetupVerify("123456", setupToken);
-res.recovery_codes; // 복구 코드 목록
-```
-
-### `twoFactorDisable(code)`
-
-2FA를 비활성화합니다.
-
-```ts
-await client.twoFactorDisable("123456");
-```
-
-### `twoFactorStatus()`
-
-2FA 활성화 여부를 조회합니다.
-
-```ts
-const res = await client.twoFactorStatus();
-res.enabled; // true | false
-```
-
-### `twoFactorVerify(twoFactorToken, code)`
-
-로그인 후 발급된 임시 토큰으로 TOTP 코드를 검증하여 최종 JWT를 발급받습니다.
-
-```ts
-const res = await client.twoFactorVerify(twoFactorToken, "123456");
-res.access_token;
-res.refresh_token;
-```
-
-### `twoFactorRecovery(twoFactorToken, recoveryCode)`
-
-복구 코드로 2FA를 우회하여 최종 JWT를 발급받습니다.
-
-```ts
-const res = await client.twoFactorRecovery(twoFactorToken, "recovery-code");
-res.access_token;
-```
-
-### `twoFactorRegenerateRecovery(code)`
-
-복구 코드를 재생성합니다.
-
-```ts
-const res = await client.twoFactorRegenerateRecovery("123456");
-res.recovery_codes;
-```
-
-## 계정 관리
-
-### `me()`
-
-현재 로그인된 사용자 정보를 반환합니다.
-
-```ts
-const res = await client.me();
-res.data; // 계정 정보
-```
-
-### `changePassword(currentPasswd, newPasswd)`
-
-비밀번호를 변경합니다.
-
-```ts
-await client.changePassword("current-pw", "new-pw");
-```
-
-### `withdraw(passwd?)`
-
-회원 탈퇴를 요청합니다.
-
-```ts
-await client.withdraw("current-pw");
-```
-
-### `reactivate(params)`
-
-휴면 계정을 재활성화합니다.
-
-```ts
-const auth = await client.reactivate({
-    email: "user@example.com",
-    passwd: "password",
-});
-```
-
-### `passwordResetRequest(email)`
-
-비밀번호 재설정 메일을 요청합니다. 인증 불필요 (공개 API).
-
-```ts
-await client.passwordResetRequest("user@example.com");
-```
-
-### `passwordResetConfirm(token, newPasswd)`
-
-이메일로 전달된 토큰으로 비밀번호를 재설정합니다. 인증 불필요 (공개 API).
-
-```ts
-await client.passwordResetConfirm("reset-token", "new-password");
-```

package/docs/api/email.md

@@ -1,37 +0,0 @@
-# 이메일 인증 / 변경
-
-## `emailVerificationSend(email)`
-
-이메일 인증 코드 또는 링크를 발송합니다. 인증 불필요 (공개 API).
-
-```ts
-await client.emailVerificationSend("user@example.com");
-```
-
-## `emailVerificationConfirm(token)`
-
-이메일로 받은 인증 토큰을 검증합니다. 인증 불필요 (공개 API).
-
-```ts
-await client.emailVerificationConfirm("verify-token-from-email");
-```
-
-## `emailVerificationStatus()`
-
-현재 로그인된 계정의 이메일 인증 상태를 조회합니다. JWT 필요.
-
-```ts
-const res = await client.emailVerificationStatus();
-res.verified; // true | false
-res.email; // 현재 이메일
-```
-
-## `emailChange(newEmail, code?)`
-
-이메일 주소를 변경합니다.
-
-```ts
-await client.emailChange("new@example.com");
-// 서버 설정에 따라 code가 필요할 수 있음
-await client.emailChange("new@example.com", "123456");
-```

package/docs/api/entity.md

@@ -1,273 +0,0 @@
-# 엔티티 CRUD / 조회
-
-## `get(entity, seq, opts?)`
-
-시퀀스 ID로 엔티티 단건을 조회합니다.
-
-| 옵션        | 타입      | 설명                                      |
-| ----------- | --------- | ----------------------------------------- |
-| `skipHooks` | `boolean` | `true`이면 `after_get` 훅을 실행하지 않음 |
-
-```ts
-const result = await client.get<Account>("account", 1);
-result.data; // Account 타입 객체
-```
-
----
-
-## `find(entity, conditions?, opts?)`
-
-조건(conditions)으로 첫 번째 일치 레코드를 조회합니다.  
-`data` 컬럼을 **항상 완전히 복호화**하여 반환합니다. 레코드가 없으면 `404` 에러가 됩니다.
-
-| 파라미터     | 타입                      | 설명                                |
-| ------------ | ------------------------- | ----------------------------------- |
-| `conditions` | `Record<string, unknown>` | 검색 조건 (인덱스 필드만 조건 가능) |
-| `skipHooks`  | `boolean`                 | `true`이면 훅 실행 건너뛰기         |
-
-```ts
-// 이메일로 계정 단건 조회
-const result = await client.find<Account>("account", {
-    email: "hong@example.com",
-});
-result.data; // Account 전체 필드 (passwd 포함)
-
-// skipHooks 옵션
-const result = await client.find<Account>(
-    "account",
-    { code: "A001" },
-    { skipHooks: true },
-);
-```
-
-> **`get` vs `find`**
->
-> - `get(entity, seq)`: seq(일련번호)를 정확히 알고 있을 때 빠르게 조회
-> - `find(entity, conditions)`: 조건으로 검색, 항상 data 전체 복호화 반환
-
----
-
-## `list(entity, params?)`
-
-페이지네이션/정렬/필터 조건으로 엔티티 목록을 조회합니다.
-
-| 파라미터     | 타입                      | 기본값  | 설명                                                |
-| ------------ | ------------------------- | ------- | --------------------------------------------------- |
-| `page`       | `number`                  | `1`     | 페이지 번호                                         |
-| `limit`      | `number`                  | `20`    | 페이지당 레코드 수 (최대 1000)                      |
-| `orderBy`    | `string`                  | —       | 정렬 기준 필드명. `-` 접두사로 내림차순 지정 가능   |
-| `orderDir`   | `"ASC" \| "DESC"`         | `"ASC"` | 정렬 방향 (`orderBy: "-field"`와 동일 효과)         |
-| `fields`     | `string[]`                | —       | 반환할 필드 목록 (**미지정 시 인덱스 필드만 반환**) |
-| `conditions` | `Record<string, unknown>` | —       | 필터 조건                                           |
-
-### `fields` — 반환 필드 지정
-
-`fields`는 `entity.json`의 `index`로 선언된 필드명만 지정할 수 있습니다.
-존재하지 않는 필드를 지정하면 서버 에러가 발생합니다.
-
-| 값                  | 설명                                                           |
-| ------------------- | -------------------------------------------------------------- |
-| 미지정 (기본값)     | 인덱스 선언 필드만 반환. **복호화를 건너뛰어 가장 빠름**       |
-| `["*"]`             | 전체 필드 반환 (복호화 수행)                                   |
-| `["name", "email"]` | 지정한 인덱스 필드만 반환. 모두 인덱스 필드면 역시 복호화 생략 |
-
-> `seq`, `created_time`, `updated_time`, `license_seq`는 `fields` 지정 여부와 무관하게 항상 포함됩니다.
-
-### `conditions` — 필터 조건
-
-인덱스 테이블의 필드(`index` / `hash` / `unique`로 선언된 필드)에만 조건을 걸 수 있습니다.
-인덱스에 없는 필드로 필터를 걸면 동작하지 않거나 에러가 발생합니다.
-
-```ts
-// 기본값 (인덱스 필드만, 가장 빠름)
-const result = await client.list("account");
-result.data.items; // 레코드 배열
-result.data.total; // 필터 조건 일치 전체 건수
-result.data.page; // 현재 페이지
-result.data.limit; // 페이지당 레코드 수
-
-// 정렬 + 필터 + 필드 선택
-const result = await client.list("account", {
-    page: 1,
-    limit: 20,
-    orderBy: "created_time",
-    orderDir: "DESC",
-    fields: ["seq", "name", "email"], // index 필드만 → 복호화 생략
-    conditions: { status: "active" },
-});
-
-// 전체 필드 반환 (fields: ["*"])
-const full = await client.list("account", {
-    fields: ["*"],
-    conditions: { status: "active" },
-});
-
-// orderBy에 - 접두사로 내림차순 (orderDir: "DESC"와 동일)
-const desc = await client.list("account", { orderBy: "-created_time" });
-```
-
----
-
-## `count(entity, conditions?)`
-
-레코드 건수를 조회합니다. `conditions`는 `list()`와 동일한 필터 규칙을 따릅니다.
-
-```ts
-const total = await client.count("account");
-total.count; // 전체 건수
-
-const active = await client.count("account", { status: "active" });
-active.count; // 조건 일치 건수
-```
-
----
-
-## `query(entity, req)`
-
-커스텀 SQL로 엔티티를 조회합니다.
-
-**제약사항**:
-
-- SELECT 쿼리만 허용 (INSERT/UPDATE/DELETE 불가)
-- 인덱스 테이블(`entity_idx_*`)만 접근 가능. 암호화된 본문 필드는 조회 불가
-- `SELECT *` 불가. 인덱스 선언 필드만 SELECT 가능
-- 최대 반환 건수: 1000
-
-`entity`는 URL 라우트 경로용 기본 엔티티명으로, 실제 조회 대상은 SQL에서 결정됩니다.
-
-| 필드     | 타입        | 설명                                            |
-| -------- | ----------- | ----------------------------------------------- |
-| `sql`    | `string`    | SELECT SQL문. 사용자 입력은 반드시 `?`로 바인딩 |
-| `params` | `unknown[]` | `?` 플레이스홀더에 바인딩할 값 배열             |
-| `limit`  | `number`    | 최대 반환 건수 (최대 1000)                      |
-
-응답: `{ ok: true, data: { items: T[], count: number } }`
-
-```ts
-// 단일 엔티티
-const result = await client.query("account", {
-    sql: "SELECT seq, name, email FROM account WHERE status = ?",
-    params: ["active"],
-    limit: 50,
-});
-result.data.items; // 레코드 배열
-result.data.count; // 반환된 건수
-
-// JOIN으로 여러 엔티티 조합
-const joined = await client.query("order", {
-    sql: `
-        SELECT o.seq, o.status, u.name AS user_name, u.email
-        FROM order o
-        JOIN account u ON u.data_seq = o.account_seq
-        WHERE o.status = ?
-        ORDER BY o.seq DESC
-    `,
-    params: ["pending"],
-    limit: 100,
-});
-```
-
-> SQL Injection 방지: 사용자 입력값은 반드시 `params`로 바인딩하세요.
-
----
-
-## `submit(entity, data, opts?)`
-
-엔티티를 생성 또는 수정합니다.
-
-- `data`에 `seq`가 **없으면** INSERT
-- `data`에 `seq`가 **있으면** UPDATE
-- `unique` 선언 필드 기준 중복 감지 시 자동 UPDATE (upsert)
-
-응답의 `seq`는 생성/수정된 레코드의 시퀀스 ID입니다.
-
-| 옵션            | 타입      | 설명                                                              |
-| --------------- | --------- | ----------------------------------------------------------------- |
-| `transactionId` | `string`  | 수동 트랜잭션 ID. 미지정 시 활성 트랜잭션 자동 사용               |
-| `skipHooks`     | `boolean` | `true`이면 `before/after_insert`, `before/after_update` 훅 미실행 |
-
-```ts
-// INSERT
-const res = await client.submit("account", {
-    name: "홍길동",
-    email: "hong@example.com",
-});
-res.seq; // 생성된 seq
-
-// UPDATE (seq 포함 시)
-await client.submit("account", { seq: 1, name: "홍길순" });
-
-// 훅 없이 저장
-await client.submit("account", { name: "테스트" }, { skipHooks: true });
-
-// 트랜잭션 내에서 — seq placeholder 활용
-await client.transStart();
-const r1 = await client.submit("order", { product_seq: 1, qty: 2 });
-// r1.seq → "$tx.0" (commit 후 실제 seq로 치환)
-await client.submit("order_item", { order_seq: r1.seq, name: "상품A" });
-await client.transCommit();
-```
-
----
-
-## `delete(entity, seq, opts?)`
-
-엔티티를 삭제합니다.
-
-| 옵션            | 타입      | 기본값  | 설명                                                      |
-| --------------- | --------- | ------- | --------------------------------------------------------- |
-| `hard`          | `boolean` | `false` | `true`이면 완전 삭제. `false`이면 소프트 삭제 (복원 가능) |
-| `transactionId` | `string`  | —       | 수동 트랜잭션 ID. 미지정 시 활성 트랜잭션 자동 사용       |
-| `skipHooks`     | `boolean` | `false` | `true`이면 `before/after_delete` 훅 미실행                |
-
-> **소프트 삭제 (기본)**: DB에서 제거하지 않고 삭제 표시만 합니다. `rollback()`으로 복원 가능합니다.
-> **하드 삭제**: DB에서 완전히 제거됩니다. 복원 불가능합니다.
-
-```ts
-// 소프트 삭제 (기본)
-const res = await client.delete("account", 2);
-res.deleted; // 삭제된 seq
-
-// 하드 삭제
-await client.delete("account", 3, { hard: true });
-```
-
----
-
-## `history(entity, seq, params?)`
-
-엔티티 단건의 변경 이력을 조회합니다. `params`는 `page`, `limit`만 지원합니다.
-
-응답 `data.items`의 각 레코드 구조:
-
-| 필드             | 타입           | 설명                                                                                 |
-| ---------------- | -------------- | ------------------------------------------------------------------------------------ |
-| `seq`            | `number`       | 이력 레코드 seq (`rollback()` 호출 시 사용)                                          |
-| `action`         | `string`       | `"INSERT"` \| `"UPDATE"` \| `"DELETE_SOFT"` \| `"DELETE_HARD"` \| `"ROLLBACK"`       |
-| `data_snapshot`  | `T \| null`    | **after 통일 모델**: INSERT/UPDATE → 변경 **후** 데이터, DELETE → 삭제 **전** 데이터 |
-| `changed_by`     | `number\|null` | 변경한 계정 seq. 시스템 변경이면 `null`                                              |
-| `changed_time`   | `string`       | 변경 시각 (ISO 8601)                                                                 |
-| `transaction_id` | `string`       | 해당 변경이 속한 트랜잭션 ID. rollback 시 이 ID 기준으로 전체 롤백됨                 |
-
-```ts
-const result = await client.history("account", 1, { page: 1, limit: 50 });
-result.data.total; // 전체 이력 건수
-result.data.items[0].action; // "UPDATE"
-result.data.items[0].data_snapshot; // 변경 후 데이터
-result.data.items[0].transaction_id; // "TX-20260201-abc123"
-```
-
----
-
-## `rollback(entity, historySeq)`
-
-특정 이력 레코드의 `transaction_id`를 조회해 **해당 트랜잭션 전체**를 롤백합니다.
-
-한 번의 트랜잭션에 여러 엔티티가 변경됐다면 모든 엔티티가 함께 되돌아갑니다.
-
-```ts
-// history()로 이력 seq 조회 후 rollback
-const hist = await client.history("account", 1);
-const targetHistorySeq = hist.data.items[0].seq;
-await client.rollback("account", targetHistorySeq);
-```