entity-server-client 0.3.2 → 1.0.1

package/src/hooks/useEntityServer.ts

@@ -1,154 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import {
-    EntityServerClient,
-    entityServer,
-    type EntityListParams,
-    type EntityQueryRequest,
-    type EntityServerClientOptions,
-} from "../index";
-
-export interface UseEntityServerOptions extends EntityServerClientOptions {
-    singleton?: boolean;
-    tokenResolver?: () => string | undefined | null;
-    /**
-     * 페이지 새로고침 후 로그인 상태를 복원할 때 사용합니다.
-     * 이 값이 있으면 마운트 시 `client.refreshToken()`을 호출해 새 access_token을 발급받습니다.
-     * `keepSession: true`와 함께 사용하면 세션 유지 타이머도 재시작됩니다.
-     * 갱신 성공 시 `onTokenRefreshed` 콜백이 호출됩니다.
-     */
-    resumeSession?: string;
-}
-
-export interface UseEntityServerResult {
-    /** EntityServerClient 인스턴스 (read 전용 메서드 직접 호출 시 사용) */
-    client: EntityServerClient;
-    /** submit 또는 delete 진행 중 여부 */
-    isPending: boolean;
-    /** 마지막 mutation 에러 (없으면 null) */
-    error: Error | null;
-    /** 에러·결과 상태 초기화 */
-    reset: () => void;
-    /** entity 데이터 생성/수정 (seq 없으면 INSERT, 있으면 UPDATE) */
-    submit: (
-        entity: string,
-        data: Record<string, unknown>,
-        opts?: { transactionId?: string; skipHooks?: boolean },
-    ) => Promise<{ ok: boolean; seq: number }>;
-    /** entity 데이터 삭제 */
-    del: (
-        entity: string,
-        seq: number,
-        opts?: { transactionId?: string; hard?: boolean; skipHooks?: boolean },
-    ) => Promise<{ ok: boolean; deleted: number }>;
-    /** 커스텀 SQL 조회 */
-    query: <T = unknown>(
-        entity: string,
-        req: EntityQueryRequest,
-    ) => Promise<{ ok: boolean; data: { items: T[]; count: number } }>;
-}
-
-/**
- * React 환경에서 EntityServerClient 인스턴스와 mutation 상태를 반환합니다.
- *
- * - `singleton=true`(기본): 패키지 전역 `entityServer` 인스턴스를 사용합니다.
- * - `singleton=false`: 컴포넌트 스코프의 새 인스턴스를 생성합니다.
- *
- * @example
- * ```tsx
- * const { submit, del, isPending, error, reset } = useEntityServer();
- *
- * const handleSave = async () => {
- *     await submit("account", { name: "홍길동" });
- * };
- * ```
- */
-export function useEntityServer(
-    options: UseEntityServerOptions = {},
-): UseEntityServerResult {
-    const {
-        singleton = true,
-        tokenResolver,
-        baseUrl,
-        token,
-        resumeSession,
-    } = options;
-
-    const [isPending, setIsPending] = useState(false);
-    const [error, setError] = useState<Error | null>(null);
-
-    // 언마운트 후 setState 방지
-    const mountedRef = useRef(true);
-    useEffect(() => {
-        mountedRef.current = true;
-        return () => {
-            mountedRef.current = false;
-        };
-    }, []);
-
-    // 새로고침 후 로그인 상태 복원: resumeSession이 있으면 마운트 시 refreshToken() 호출
-    const resumeTokenRef = useRef(resumeSession);
-    useEffect(() => {
-        const storedRefreshToken = resumeTokenRef.current;
-        if (!storedRefreshToken) return;
-        client.refreshToken(storedRefreshToken).catch(() => {
-            // refresh_token 만료 등 — onSessionExpired 콜백이 이미 처리
-        });
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
-
-    const client = useMemo(() => {
-        const c = singleton
-            ? entityServer
-            : new EntityServerClient({ baseUrl, token });
-
-        if (singleton) {
-            c.configure({ baseUrl, token });
-        }
-
-        const resolvedToken = tokenResolver?.();
-        if (typeof resolvedToken === "string") {
-            c.setToken(resolvedToken);
-        }
-
-        return c;
-    }, [singleton, tokenResolver, baseUrl, token]);
-
-    const run = useCallback(async <T>(fn: () => Promise<T>): Promise<T> => {
-        if (mountedRef.current) {
-            setIsPending(true);
-            setError(null);
-        }
-        try {
-            const result = await fn();
-            return result;
-        } catch (err) {
-            const e = err instanceof Error ? err : new Error(String(err));
-            if (mountedRef.current) setError(e);
-            throw e;
-        } finally {
-            if (mountedRef.current) setIsPending(false);
-        }
-    }, []);
-
-    const submit = useCallback<UseEntityServerResult["submit"]>(
-        (entity, data, opts) => run(() => client.submit(entity, data, opts)),
-        [client, run],
-    );
-
-    const del = useCallback<UseEntityServerResult["del"]>(
-        (entity, seq, opts) => run(() => client.delete(entity, seq, opts)),
-        [client, run],
-    );
-
-    const query = useCallback<UseEntityServerResult["query"]>(
-        (entity, req) => run(() => client.query(entity, req)),
-        [client, run],
-    );
-
-    const reset = useCallback(() => {
-        setIsPending(false);
-        setError(null);
-    }, []);
-
-    return { client, isPending, error, reset, submit, del, query };
-}

package/src/mixins/auth.ts

@@ -1,143 +0,0 @@
-import type { GConstructor, EntityServerClientBase } from "../client/base";
-
-export function AuthMixin<TBase extends GConstructor<EntityServerClientBase>>(
-    Base: TBase,
-) {
-    return class AuthMixinClass extends Base {
-        // ─── 인증 ─────────────────────────────────────────────────────────────
-
-        /**
-         * 서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
-         *
-         * 서버가 `packet_encryption: true`를 응답하면 이후 모든 요청에 암호화가 자동 적용됩니다.
-         *
-         * ```ts
-         * await client.checkHealth();
-         * await client.login(email, password);
-         * ```
-         */
-        async checkHealth(): Promise<{
-            ok: boolean;
-            packet_encryption?: boolean;
-            packet_mode?: string;
-            packet_token?: string;
-        }> {
-            const res = await fetch(`${this.baseUrl}/v1/health`, {
-                signal: AbortSignal.timeout(3000),
-                credentials: "include",
-            });
-            const data = (await res.json()) as {
-                ok: boolean;
-                packet_encryption?: boolean;
-                packet_mode?: string;
-                packet_token?: string;
-            };
-            if (data.packet_encryption) this.encryptRequests = true;
-            if (typeof data.packet_token === "string") {
-                this.anonymousPacketToken = data.packet_token;
-            }
-            return data;
-        }
-
-        /** 로그인 후 `access_token`을 내부 상태에 저장합니다. */
-        async login(
-            email: string,
-            password: string,
-        ): Promise<{
-            access_token: string;
-            refresh_token: string;
-            expires_in: number;
-            force_password_change?: boolean;
-            password_expired?: boolean;
-            password_expires_in_days?: number;
-        }> {
-            const data = await this._request<{
-                data: {
-                    access_token: string;
-                    refresh_token: string;
-                    expires_in: number;
-                    force_password_change?: boolean;
-                    password_expired?: boolean;
-                    password_expires_in_days?: number;
-                };
-            }>("POST", "/v1/auth/login", { email, passwd: password }, false);
-            this.token = data.data.access_token;
-            if (this.keepSession)
-                this._scheduleKeepSession(
-                    data.data.refresh_token,
-                    data.data.expires_in,
-                    (rt) => this.refreshToken(rt),
-                );
-            return data.data;
-        }
-
-        /** Refresh Token으로 Access Token을 재발급받아 내부 토큰을 교체합니다. */
-        async refreshToken(
-            refreshToken: string,
-        ): Promise<{ access_token: string; expires_in: number }> {
-            const data = await this._request<{
-                data: { access_token: string; expires_in: number };
-            }>(
-                "POST",
-                "/v1/auth/refresh",
-                { refresh_token: refreshToken },
-                false,
-            );
-            this.token = data.data.access_token;
-            if (this.keepSession)
-                this._scheduleKeepSession(
-                    refreshToken,
-                    data.data.expires_in,
-                    (rt) => this.refreshToken(rt),
-                );
-            return data.data;
-        }
-
-        /**
-         * 서버에 로그아웃을 요청하고 내부 토큰을 초기화합니다.
-         * refresh_token을 서버에 전달해 무효화합니다.
-         */
-        async logout(refreshToken: string): Promise<{ ok: boolean }> {
-            this.stopKeepSession();
-            const data = await this._request<{ ok: boolean }>(
-                "POST",
-                "/v1/auth/logout",
-                { refresh_token: refreshToken },
-                false,
-            );
-            this.token = "";
-            return data;
-        }
-
-        /** 현재 로그인된 사용자 정보를 반환합니다. */
-        me<T = Record<string, unknown>>(): Promise<{ ok: boolean; data: T }> {
-            return this._request("GET", "/v1/auth/me");
-        }
-
-        /** 회원 탈퇴를 요청합니다. */
-        withdraw(passwd?: string): Promise<{ ok: boolean }> {
-            return this._request(
-                "POST",
-                "/v1/auth/withdraw",
-                passwd ? { passwd } : {},
-            );
-        }
-
-        /**
-         * 휴면 계정을 재활성화합니다.
-         * 비밀번호 또는 OAuth(provider + code)로 본인 확인합니다.
-         */
-        reactivate(params: {
-            email: string;
-            passwd?: string;
-            provider?: string;
-            code?: string;
-        }): Promise<{
-            access_token: string;
-            refresh_token: string;
-            expires_in: number;
-        }> {
-            return this._request("POST", "/v1/auth/reactivate", params, false);
-        }
-    };
-}

package/src/mixins/entity.ts

@@ -1,205 +0,0 @@
-import type {
-    EntityHistoryRecord,
-    EntityListParams,
-    EntityListResult,
-    EntityQueryRequest,
-} from "../types";
-import { buildQuery } from "../client/utils";
-import type { GConstructor, EntityServerClientBase } from "../client/base";
-
-export function EntityMixin<TBase extends GConstructor<EntityServerClientBase>>(
-    Base: TBase,
-) {
-    return class EntityMixinClass extends Base {
-        // ─── 트랜잭션 ─────────────────────────────────────────────────────────
-
-        /** 트랜잭션을 시작하고 활성 트랜잭션 ID를 저장합니다. */
-        async transStart(): Promise<string> {
-            const res = await this._request<{
-                ok: boolean;
-                transaction_id: string;
-            }>("POST", "/v1/transaction/start", undefined, false);
-            this.activeTxId = res.transaction_id;
-            return this.activeTxId;
-        }
-
-        /** 활성 트랜잭션(또는 전달된 transactionId)을 롤백합니다. */
-        transRollback(transactionId?: string): Promise<{ ok: boolean }> {
-            const txId = transactionId ?? this.activeTxId;
-            if (!txId)
-                return Promise.reject(
-                    new Error(
-                        "No active transaction. Call transStart() first.",
-                    ),
-                );
-            this.activeTxId = null;
-            return this._request("POST", `/v1/transaction/rollback/${txId}`);
-        }
-
-        /**
-         * 활성 트랜잭션(또는 전달된 transactionId)을 커밋합니다.
-         *
-         * @returns `results` 배열: commit된 각 작업의 `entity`, `action`, `seq`
-         */
-        transCommit(transactionId?: string): Promise<{
-            ok: boolean;
-            results: Array<{ entity: string; action: string; seq: number }>;
-        }> {
-            const txId = transactionId ?? this.activeTxId;
-            if (!txId)
-                return Promise.reject(
-                    new Error(
-                        "No active transaction. Call transStart() first.",
-                    ),
-                );
-            this.activeTxId = null;
-            return this._request("POST", `/v1/transaction/commit/${txId}`);
-        }
-
-        // ─── 엔티티 CRUD ──────────────────────────────────────────────────────
-
-        /** 시퀀스 ID로 엔티티 단건을 조회합니다. */
-        get<T = unknown>(
-            entity: string,
-            seq: number,
-            opts: { skipHooks?: boolean } = {},
-        ): Promise<{ ok: boolean; data: T }> {
-            const q = opts.skipHooks ? "?skipHooks=true" : "";
-            return this._request("GET", `/v1/entity/${entity}/${seq}${q}`);
-        }
-
-        /** 조건으로 엔티티 단건을 조회합니다. data 컬럼을 완전히 복호화하여 반환합니다. */
-        find<T = unknown>(
-            entity: string,
-            conditions?: Record<string, unknown>,
-            opts: { skipHooks?: boolean } = {},
-        ): Promise<{ ok: boolean; data: T }> {
-            const q = opts.skipHooks ? "?skipHooks=true" : "";
-            return this._request(
-                "POST",
-                `/v1/entity/${entity}/find${q}`,
-                conditions ?? {},
-            );
-        }
-
-        /** 페이지네이션/정렬/필터 조건으로 엔티티 목록을 조회합니다. */
-        list<T = unknown>(
-            entity: string,
-            params: EntityListParams = {},
-        ): Promise<{ ok: boolean; data: EntityListResult<T> }> {
-            const { conditions, fields, orderDir, orderBy, ...rest } = params;
-            const queryObj: Record<string, unknown> = {
-                page: 1,
-                limit: 20,
-                ...rest,
-            };
-            if (orderBy)
-                queryObj.orderBy =
-                    orderDir === "DESC" ? `-${orderBy}` : orderBy;
-            if (fields?.length) queryObj.fields = fields.join(",");
-            return this._request(
-                "POST",
-                `/v1/entity/${entity}/list?${buildQuery(queryObj)}`,
-                conditions ?? {},
-            );
-        }
-
-        /**
-         * 엔티티 총 건수를 조회합니다.
-         *
-         * @param conditions 필터 조건 (예: `{ status: "active" }`)
-         */
-        count(
-            entity: string,
-            conditions?: Record<string, unknown>,
-        ): Promise<{ ok: boolean; count: number }> {
-            return this._request(
-                "POST",
-                `/v1/entity/${entity}/count`,
-                conditions ?? {},
-            );
-        }
-
-        /**
-         * 커스텀 SQL로 엔티티를 조회합니다.
-         *
-         * SELECT 전용이며 인덱스 테이블만 조회 가능합니다. JOIN 지원.
-         */
-        query<T = unknown>(
-            entity: string,
-            req: EntityQueryRequest,
-        ): Promise<{ ok: boolean; data: { items: T[]; count: number } }> {
-            return this._request("POST", `/v1/entity/${entity}/query`, req);
-        }
-
-        /** 엔티티 데이터를 생성/수정(Submit)합니다. `seq`가 없으면 INSERT, 있으면 UPDATE입니다. */
-        submit(
-            entity: string,
-            data: Record<string, unknown>,
-            opts: { transactionId?: string; skipHooks?: boolean } = {},
-        ): Promise<{ ok: boolean; seq: number }> {
-            const txId = opts.transactionId ?? this.activeTxId;
-            const extraHeaders = txId
-                ? { "X-Transaction-ID": txId }
-                : undefined;
-            const q = opts.skipHooks ? "?skipHooks=true" : "";
-            return this._request(
-                "POST",
-                `/v1/entity/${entity}/submit${q}`,
-                data,
-                true,
-                extraHeaders,
-            );
-        }
-
-        /** 시퀀스 ID로 엔티티를 삭제합니다(`hard=true`면 하드 삭제, 기본은 소프트 삭제). */
-        delete(
-            entity: string,
-            seq: number,
-            opts: {
-                transactionId?: string;
-                hard?: boolean;
-                skipHooks?: boolean;
-            } = {},
-        ): Promise<{ ok: boolean; deleted: number }> {
-            const params = new URLSearchParams();
-            if (opts.hard) params.set("hard", "true");
-            if (opts.skipHooks) params.set("skipHooks", "true");
-            const q = params.size ? `?${params}` : "";
-            const txId = opts.transactionId ?? this.activeTxId;
-            const extraHeaders = txId
-                ? { "X-Transaction-ID": txId }
-                : undefined;
-            return this._request(
-                "POST",
-                `/v1/entity/${entity}/delete/${seq}${q}`,
-                undefined,
-                true,
-                extraHeaders,
-            );
-        }
-
-        /** 엔티티 단건의 변경 이력을 조회합니다. */
-        history<T = unknown>(
-            entity: string,
-            seq: number,
-            params: Pick<EntityListParams, "page" | "limit"> = {},
-        ): Promise<{
-            ok: boolean;
-            data: EntityListResult<EntityHistoryRecord<T>>;
-        }> {
-            return this._request(
-                "GET",
-                `/v1/entity/${entity}/history/${seq}?${buildQuery({ page: 1, limit: 50, ...params })}`,
-            );
-        }
-
-        /** 특정 이력 시점으로 엔티티를 롤백합니다. */
-        rollback(entity: string, historySeq: number): Promise<{ ok: boolean }> {
-            return this._request(
-                "POST",
-                `/v1/entity/${entity}/rollback/${historySeq}`,
-            );
-        }
-    };
-}

package/src/mixins/file.ts

@@ -1,99 +0,0 @@
-import type { FileMeta, FileUploadOptions } from "../types";
-import type { GConstructor, EntityServerClientBase } from "../client/base";
-
-export function FileMixin<TBase extends GConstructor<EntityServerClientBase>>(
-    Base: TBase,
-) {
-    return class FileMixinClass extends Base {
-        // ─── 파일 관리 ────────────────────────────────────────────────────────
-
-        /**
-         * 파일을 업로드합니다. (multipart/form-data)
-         *
-         * ```ts
-         * const input = document.querySelector('input[type="file"]');
-         * const result = await client.fileUpload("product", input.files[0]);
-         * console.log(result.data.uuid);
-         * ```
-         */
-        async fileUpload(
-            entity: string,
-            file: File | Blob,
-            opts: FileUploadOptions = {},
-        ): Promise<{ ok: boolean; uuid: string; data: FileMeta }> {
-            const form = new FormData();
-            form.append(
-                "file",
-                file,
-                file instanceof File ? file.name : "upload",
-            );
-            if (opts.refSeq != null)
-                form.append("ref_seq", String(opts.refSeq));
-            if (opts.isPublic != null)
-                form.append("is_public", opts.isPublic ? "true" : "false");
-            return this._requestForm(
-                "POST",
-                `/v1/files/${entity}/upload`,
-                form,
-            );
-        }
-
-        /** 파일을 다운로드합니다. `ArrayBuffer`를 반환합니다. */
-        fileDownload(entity: string, uuid: string): Promise<ArrayBuffer> {
-            return this._requestBinary(
-                "POST",
-                `/v1/files/${entity}/download/${uuid}`,
-                {},
-            );
-        }
-
-        /** 파일을 삭제합니다. */
-        fileDelete(
-            entity: string,
-            uuid: string,
-        ): Promise<{ ok: boolean; uuid: string; deleted: boolean }> {
-            return this._request(
-                "POST",
-                `/v1/files/${entity}/delete/${uuid}`,
-                {},
-            );
-        }
-
-        /** 엔티티에 연결된 파일 목록을 조회합니다. */
-        fileList(
-            entity: string,
-            opts: { refSeq?: number } = {},
-        ): Promise<{
-            ok: boolean;
-            data: { items: FileMeta[]; total: number };
-        }> {
-            return this._request(
-                "POST",
-                `/v1/files/${entity}/list`,
-                opts.refSeq ? { ref_seq: opts.refSeq } : {},
-            );
-        }
-
-        /** 파일 메타 정보를 조회합니다. */
-        fileMeta(
-            entity: string,
-            uuid: string,
-        ): Promise<{ ok: boolean; data: FileMeta }> {
-            return this._request(
-                "POST",
-                `/v1/files/${entity}/meta/${uuid}`,
-                {},
-            );
-        }
-
-        /** 임시 파일 접근 토큰을 발급합니다. */
-        fileToken(uuid: string): Promise<{ ok: boolean; token: string }> {
-            return this._request("POST", `/v1/files/token/${uuid}`, {});
-        }
-
-        /** 파일 인라인 뷰 URL을 반환합니다. (fetch 없음, URL 조합만) */
-        fileUrl(uuid: string): string {
-            return `${this.baseUrl}/v1/files/${uuid}`;
-        }
-    };
-}