entity-server-client 0.2.6 → 0.3.1

package/docs/react.md

@@ -26,6 +26,64 @@ export function AccountPage() {
 }
 ```
 
+## `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`)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "entity-server-client",
-    "version": "0.2.6",
+    "version": "0.3.1",
     "license": "MIT",
     "type": "module",
     "publishConfig": {
@@ -11,6 +11,10 @@
             "types": "./dist/index.d.ts",
             "default": "./dist/index.js"
         },
+        "./packet": {
+            "types": "./dist/packet.d.ts",
+            "default": "./dist/packet.js"
+        },
         "./react": {
             "types": "./dist/react.d.ts",
             "default": "./dist/react.js"
@@ -20,6 +24,7 @@
     "types": "./dist/index.d.ts",
     "scripts": {
         "build": "tsc --declaration --emitDeclarationOnly && node build.mjs",
+        "test": "npm run build && node --test tests/**/*.test.mjs",
         "prepublishOnly": "npm run build"
     },
     "peerDependencies": {

package/src/EntityServerClient.ts

@@ -4,51 +4,25 @@
  *
  * 절(section)별 구현:
  *   src/client/base.ts      — 상태·생성자·공통 헬퍼
- *   src/mixins/auth.ts      — 인증 (로그인/로그아웃/2FA/OAuth 등)
+ *   src/mixins/auth.ts      — 인증 (로그인/로그아웃/me/트랜잭션 등)
  *   src/mixins/entity.ts    — 트랜잭션 & 엔티티 CRUD
- *   src/mixins/push.ts      — 푸시 디바이스 관리 & 발송
- *   src/mixins/email.ts     — 이메일 인증/변경
- *   src/mixins/sms.ts       — SMS 발송/인증
+ *   src/mixins/push.ts      — 푸시 디바이스 관리
  *   src/mixins/smtp.ts      — SMTP 메일 발송
- *   src/mixins/alimtalk.ts  — 알림톡/친구톡
- *   src/mixins/pg.ts        — PG 결제 게이트웨이
  *   src/mixins/file.ts      — 파일 스토리지
- *   src/mixins/identity.ts  — 본인인증
- *   src/mixins/utils.ts     — QR코드/바코드
+ *   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 { EmailMixin } from "./mixins/email";
-import { SmsMixin } from "./mixins/sms";
 import { SmtpMixin } from "./mixins/smtp";
-import { AlimtalkMixin } from "./mixins/alimtalk";
-import { PgMixin } from "./mixins/pg";
 import { FileMixin } from "./mixins/file";
-import { IdentityMixin } from "./mixins/identity";
 import { UtilsMixin } from "./mixins/utils";
 
 // ─── Composed class ───────────────────────────────────────────────────────────
 
 export class EntityServerClient extends UtilsMixin(
-    IdentityMixin(
-        FileMixin(
-            PgMixin(
-                AlimtalkMixin(
-                    SmtpMixin(
-                        SmsMixin(
-                            EmailMixin(
-                                PushMixin(
-                                    EntityMixin(
-                                        AuthMixin(EntityServerClientBase),
-                                    ),
-                                ),
-                            ),
-                        ),
-                    ),
-                ),
-            ),
-        ),
+    FileMixin(
+        SmtpMixin(PushMixin(EntityMixin(AuthMixin(EntityServerClientBase)))),
     ),
 ) {}

package/src/client/base.ts

@@ -9,6 +9,7 @@ export type GConstructor<T = object> = new (...args: any[]) => T;
 export class EntityServerClientBase {
     baseUrl: string;
     token: string;
+    anonymousPacketToken: string;
     apiKey: string;
     hmacSecret: string;
     encryptRequests: boolean;
@@ -17,10 +18,7 @@ export class EntityServerClientBase {
     // 세션 유지 관련
     keepSession: boolean;
     refreshBuffer: number;
-    onTokenRefreshed?: (
-        accessToken: string,
-        expiresIn: number,
-    ) => void;
+    onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
     onSessionExpired?: (error: Error) => void;
     _sessionRefreshToken: string | null = null;
     _refreshTimer: ReturnType<typeof setTimeout> | null = null;
@@ -31,17 +29,14 @@ export class EntityServerClientBase {
      * EntityServerClient 인스턴스를 생성합니다.
      *
      * 기본값:
-     * - `baseUrl`: `VITE_ENTITY_SERVER_URL` 또는 `http://localhost:47200`
+     * - `baseUrl`: `VITE_ENTITY_SERVER_URL` 또는 상대 경로(`""`)
      */
     constructor(options: EntityServerClientOptions = {}) {
         const envBaseUrl = readEnv("VITE_ENTITY_SERVER_URL");
 
-        this.baseUrl = (
-            options.baseUrl ??
-            envBaseUrl ??
-            "http://localhost:47200"
-        ).replace(/\/$/, "");
+        this.baseUrl = (options.baseUrl ?? envBaseUrl ?? "").replace(/\/$/, "");
         this.token = options.token ?? "";
+        this.anonymousPacketToken = options.anonymousPacketToken ?? "";
         this.apiKey = options.apiKey ?? "";
         this.hmacSecret = options.hmacSecret ?? "";
         this.encryptRequests = options.encryptRequests ?? false;
@@ -53,8 +48,13 @@ export class EntityServerClientBase {
 
     /** baseUrl, token, encryptRequests 값을 런타임에 갱신합니다. */
     configure(options: Partial<EntityServerClientOptions>): void {
-        if (options.baseUrl) this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        if (typeof options.baseUrl === "string") {
+            this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        }
         if (typeof options.token === "string") this.token = options.token;
+        if (typeof options.anonymousPacketToken === "string") {
+            this.anonymousPacketToken = options.anonymousPacketToken;
+        }
         if (typeof options.encryptRequests === "boolean")
             this.encryptRequests = options.encryptRequests;
         if (typeof options.apiKey === "string") this.apiKey = options.apiKey;
@@ -75,6 +75,11 @@ export class EntityServerClientBase {
         this.token = token;
     }
 
+    /** 익명 패킷 암호화용 토큰을 설정합니다. */
+    setAnonymousPacketToken(token: string): void {
+        this.anonymousPacketToken = token;
+    }
+
     /** HMAC 인증용 API Key를 설정합니다. */
     setApiKey(apiKey: string): void {
         this.apiKey = apiKey;
@@ -152,7 +157,10 @@ export class EntityServerClientBase {
         contentType = "application/json",
         requireEncrypted = false,
     ): T {
-        const key = derivePacketKey(this.hmacSecret, this.token);
+        const key = derivePacketKey(
+            this.hmacSecret,
+            this.token || this.anonymousPacketToken,
+        );
         return parseRequestBody<T>(body, contentType, requireEncrypted, key);
     }
 
@@ -162,12 +170,74 @@ export class EntityServerClientBase {
         return {
             baseUrl: this.baseUrl,
             token: this.token,
+            anonymousPacketToken: this.anonymousPacketToken,
             apiKey: this.apiKey,
             hmacSecret: this.hmacSecret,
             encryptRequests: this.encryptRequests,
         };
     }
 
+    /**
+     * 임의 경로에 JSON 요청을 보냅니다. 응답이 JSON이면 파싱, octet-stream이면 자동 복호화합니다.
+     * `ok` 필드를 강제하지 않아 go서버/앱서버 신규 라우트 등 자유 응답 포맷에 사용합니다.
+     * `encryptRequests: true`이면 요청 바디도 자동 암호화됩니다.
+     */
+    requestJson<T>(
+        method: string,
+        path: string,
+        body?: unknown,
+        withAuth = true,
+        extraHeaders?: Record<string, string>,
+    ): Promise<T> {
+        return entityRequest<T>(
+            this._reqOpts,
+            method,
+            path,
+            body,
+            withAuth,
+            extraHeaders,
+            false,
+        );
+    }
+
+    /**
+     * 임의 경로에 요청을 보내고 바이너리(ArrayBuffer)를 반환합니다.
+     * 이미지, PDF, 압축 파일 등 바이너리 응답이 오는 엔드포인트에 사용합니다.
+     */
+    requestBinary(
+        method: string,
+        path: string,
+        body?: unknown,
+        withAuth = true,
+    ): Promise<ArrayBuffer> {
+        return this._requestBinary(method, path, body, withAuth);
+    }
+
+    /**
+     * multipart/form-data 요청을 보냅니다. 파일 업로드 등에 사용합니다.
+     * 응답은 JSON으로 파싱하여 반환합니다.
+     */
+    requestForm<T>(
+        method: string,
+        path: string,
+        form: FormData,
+        withAuth = true,
+    ): Promise<T> {
+        return this._requestForm<T>(method, path, form, withAuth);
+    }
+
+    /**
+     * multipart/form-data 요청을 보내고 바이너리(ArrayBuffer)를 반환합니다.
+     */
+    requestFormBinary(
+        method: string,
+        path: string,
+        form: FormData,
+        withAuth = true,
+    ): Promise<ArrayBuffer> {
+        return this._requestFormBinary(method, path, form, withAuth);
+    }
+
     _request<T>(
         method: string,
         path: string,
@@ -182,6 +252,7 @@ export class EntityServerClientBase {
             body,
             withAuth,
             extraHeaders,
+            true,
         );
     }
 
@@ -203,6 +274,7 @@ export class EntityServerClientBase {
             method,
             headers,
             ...(body != null ? { body: JSON.stringify(body) } : {}),
+            credentials: "include",
         });
 
         if (!res.ok) {
@@ -231,6 +303,7 @@ export class EntityServerClientBase {
             method,
             headers,
             body: form,
+            credentials: "include",
         });
 
         const data = await res.json();
@@ -243,4 +316,33 @@ export class EntityServerClientBase {
         }
         return data as T;
     }
+
+    /** multipart/form-data 요청을 보내고 바이너리(ArrayBuffer)를 반환합니다. */
+    async _requestFormBinary(
+        method: string,
+        path: string,
+        form: FormData,
+        withAuth = true,
+    ): Promise<ArrayBuffer> {
+        const headers: Record<string, string> = {};
+        if (withAuth && this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+
+        const res = await fetch(this.baseUrl + path, {
+            method,
+            headers,
+            body: form,
+            credentials: "include",
+        });
+
+        if (!res.ok) {
+            const text = await res.text();
+            const err = new Error(`HTTP ${res.status}: ${text}`);
+            (err as { status?: number }).status = res.status;
+            throw err;
+        }
+
+        return res.arrayBuffer();
+    }
 }

package/src/client/packet.ts

@@ -1,9 +1,8 @@
-// @ts-ignore
-import { xchacha20poly1305 } from "@noble/ciphers/chacha";
-// @ts-ignore
-import { sha256 } from "@noble/hashes/sha2";
-// @ts-ignore
-import { hkdf } from "@noble/hashes/hkdf";
+import {
+    derivePacketKey as derivePacketKeyCore,
+    encryptPacket as encryptPacketCore,
+    decryptPacket as decryptPacketCore,
+} from "../packet";
 
 /**
  * 패킷 암호화 키를 유도합니다.
@@ -11,10 +10,7 @@ import { hkdf } from "@noble/hashes/hkdf";
  * - JWT  모드: HKDF-SHA256(jwt_token, "entity-server:packet-encryption")
  */
 export function derivePacketKey(hmacSecret: string, token: string): Uint8Array {
-    const ikm = hmacSecret || token;
-    const salt = new TextEncoder().encode("entity-server:hkdf:v1");
-    const info = new TextEncoder().encode("entity-server:packet-encryption");
-    return hkdf(sha256, new TextEncoder().encode(ikm), salt, info, 32);
+    return derivePacketKeyCore(hmacSecret || token);
 }
 
 /**
@@ -26,18 +22,7 @@ export function encryptPacket(
     plaintext: Uint8Array,
     key: Uint8Array,
 ): Uint8Array {
-    const magicLen = 2 + (key[31] % 14);
-    const magic = new Uint8Array(magicLen);
-    const nonce = new Uint8Array(24);
-    crypto.getRandomValues(magic);
-    crypto.getRandomValues(nonce);
-    const cipher = xchacha20poly1305(key, nonce);
-    const ciphertext = cipher.encrypt(plaintext);
-    const result = new Uint8Array(magicLen + 24 + ciphertext.length);
-    result.set(magic, 0);
-    result.set(nonce, magicLen);
-    result.set(ciphertext, magicLen + 24);
-    return result;
+    return encryptPacketCore(plaintext, key);
 }
 
 /**
@@ -46,15 +31,7 @@ export function encryptPacket(
  * K = 2 + key[31] % 14 (패킷 키에서 자동 파생)
  */
 export function decryptPacket<T>(buffer: ArrayBuffer, key: Uint8Array): T {
-    const magicLen = 2 + (key[31] % 14);
-    const data = new Uint8Array(buffer);
-    if (data.length < magicLen + 24 + 16) {
-        throw new Error("Encrypted packet too short");
-    }
-    const nonce = data.slice(magicLen, magicLen + 24);
-    const ciphertext = data.slice(magicLen + 24);
-    const cipher = xchacha20poly1305(key, nonce);
-    const plaintext = cipher.decrypt(ciphertext);
+    const plaintext = decryptPacketCore(buffer, key);
     return JSON.parse(new TextDecoder().decode(plaintext)) as T;
 }
 

package/src/client/request.ts

@@ -4,11 +4,31 @@ import { buildHmacHeaders } from "./hmac";
 export interface RequestOptions {
     baseUrl: string;
     token: string;
+    anonymousPacketToken: string;
     apiKey: string;
     hmacSecret: string;
     encryptRequests: boolean;
 }
 
+function resolvePacketSource(opts: RequestOptions): string {
+    return opts.hmacSecret || opts.token || opts.anonymousPacketToken;
+}
+
+async function readErrorMessage(res: Response): Promise<string> {
+    const contentType = res.headers.get("Content-Type") ?? "";
+    if (contentType.includes("application/json")) {
+        const data = (await res.json().catch(() => null)) as {
+            error?: string;
+            message?: string;
+        } | null;
+        if (data?.error) return data.error;
+        if (data?.message) return data.message;
+    }
+
+    const text = await res.text().catch(() => "");
+    return text || `HTTP ${res.status}`;
+}
+
 /**
  * Entity Server에 HTTP 요청을 보냅니다.
  *
@@ -23,9 +43,18 @@ export async function entityRequest<T>(
     body?: unknown,
     withAuth = true,
     extraHeaders: Record<string, string> = {},
+    requireOkShape = true,
 ): Promise<T> {
-    const { baseUrl, token, apiKey, hmacSecret, encryptRequests } = opts;
+    const {
+        baseUrl,
+        token,
+        apiKey,
+        hmacSecret,
+        encryptRequests,
+        anonymousPacketToken,
+    } = opts;
     const isHmacMode = withAuth && !!(apiKey && hmacSecret);
+    const packetSource = resolvePacketSource(opts);
 
     const headers: Record<string, string> = {
         "Content-Type": "application/json",
@@ -39,18 +68,23 @@ export async function entityRequest<T>(
     if (body != null) {
         const shouldEncrypt =
             encryptRequests &&
-            withAuth &&
-            (token || isHmacMode) &&
+            !!packetSource &&
             method !== "GET" &&
             method !== "HEAD";
 
         if (shouldEncrypt) {
-            const key = derivePacketKey(hmacSecret, token);
+            const key = derivePacketKey(
+                hmacSecret,
+                token || anonymousPacketToken,
+            );
             fetchBody = encryptPacket(
                 new TextEncoder().encode(JSON.stringify(body)),
                 key,
             );
             headers["Content-Type"] = "application/octet-stream";
+            if (!token && !isHmacMode && anonymousPacketToken) {
+                headers["X-Packet-Token"] = anonymousPacketToken;
+            }
         } else {
             fetchBody = JSON.stringify(body);
         }
@@ -73,21 +107,33 @@ export async function entityRequest<T>(
         method,
         headers,
         ...(fetchBody != null ? { body: fetchBody as BodyInit } : {}),
+        credentials: "include",
     });
 
+    if (!res.ok) {
+        const err = new Error(await readErrorMessage(res));
+        (err as { status?: number }).status = res.status;
+        throw err;
+    }
+
     const contentType = res.headers.get("Content-Type") ?? "";
     if (contentType.includes("application/octet-stream")) {
-        const key = derivePacketKey(hmacSecret, token);
+        const key = derivePacketKey(hmacSecret, token || anonymousPacketToken);
         return decryptPacket<T>(await res.arrayBuffer(), key);
     }
 
+    if (!contentType.includes("application/json")) {
+        return (await res.text()) as T;
+    }
+
     const data = await res.json();
-    if (!data.ok) {
+    if (requireOkShape && !data.ok) {
         const err = new Error(
             data.message ?? `EntityServer error (HTTP ${res.status})`,
         );
         (err as { status?: number }).status = res.status;
         throw err;
     }
+
     return data as T;
 }

package/src/client/utils.ts

@@ -11,12 +11,11 @@ export function readEnv(name: string): string | undefined {
     if (meta?.env?.[name] != null) return meta.env[name];
 
     // Node.js (process.env)
-    if (
-        typeof process !== "undefined" &&
-        process.env &&
-        process.env[name] != null
-    ) {
-        return process.env[name];
+    const _proc = (
+        globalThis as { process?: { env?: Record<string, string | undefined> } }
+    ).process;
+    if (_proc?.env?.[name] != null) {
+        return _proc.env[name];
     }
 
     return undefined;