entity-server-client 0.2.5 → 0.2.6

package/src/mixins/auth.ts

@@ -0,0 +1,287 @@
+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;
+        }> {
+            const res = await fetch(`${this.baseUrl}/v1/health`, {
+                signal: AbortSignal.timeout(3000),
+            });
+            const data = (await res.json()) as {
+                ok: boolean;
+                packet_encryption?: boolean;
+            };
+            if (data.packet_encryption) this.encryptRequests = true;
+            return data;
+        }
+
+        /** 로그인 후 `access_token`을 내부 상태에 저장합니다. */
+        async login(
+            email: string,
+            password: string,
+        ): Promise<{
+            access_token: string;
+            refresh_token: string;
+            expires_in: number;
+        }> {
+            const data = await this._request<{
+                data: {
+                    access_token: string;
+                    refresh_token: string;
+                    expires_in: 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");
+        }
+
+        /** 비밀번호를 변경합니다. */
+        changePassword(
+            currentPasswd: string,
+            newPasswd: string,
+        ): Promise<{ ok: boolean }> {
+            return this._request("POST", "/v1/auth/change-password", {
+                current_passwd: currentPasswd,
+                new_passwd: newPasswd,
+            });
+        }
+
+        /** 회원 탈퇴를 요청합니다. */
+        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);
+        }
+
+        /** 비밀번호 재설정 메일을 요청합니다. */
+        passwordResetRequest(email: string): Promise<{ ok: boolean }> {
+            return this._request(
+                "POST",
+                "/v1/auth/password-reset",
+                { email },
+                false,
+            );
+        }
+
+        /** 이메일로 전달된 토큰으로 비밀번호를 재설정합니다. */
+        passwordResetConfirm(
+            token: string,
+            newPasswd: string,
+        ): Promise<{ ok: boolean }> {
+            return this._request(
+                "POST",
+                "/v1/auth/password-reset/confirm",
+                { token, new_passwd: newPasswd },
+                false,
+            );
+        }
+
+        // ─── OAuth 연동 ───────────────────────────────────────────────────────
+
+        /** OAuth 프로바이더를 현재 계정에 연동합니다. */
+        oauthLink(
+            provider: string,
+            code: string,
+            state?: string,
+        ): Promise<{ ok: boolean; message: string; provider: string }> {
+            return this._request("POST", "/v1/auth/oauth/link", {
+                provider,
+                code,
+                ...(state ? { state } : {}),
+            });
+        }
+
+        /** OAuth 프로바이더 연동을 해제합니다. */
+        oauthUnlink(
+            provider: string,
+        ): Promise<{ ok: boolean; message: string; provider: string }> {
+            return this._request("DELETE", `/v1/auth/oauth/link/${provider}`);
+        }
+
+        /** 현재 계정에 연동된 OAuth 프로바이더 목록을 반환합니다. */
+        oauthProviders(): Promise<{
+            ok: boolean;
+            data: Array<{
+                provider: string;
+                email?: string;
+                linked_at?: string;
+            }>;
+        }> {
+            return this._request("GET", "/v1/auth/oauth/providers");
+        }
+
+        /** 특정 OAuth 프로바이더의 액세스 토큰을 갱신합니다. */
+        oauthTokenRefresh(provider: string): Promise<{
+            ok: boolean;
+            access_token: string;
+            expires_at?: string;
+        }> {
+            return this._request("POST", `/v1/auth/oauth/refresh/${provider}`);
+        }
+
+        // ─── 2단계 인증 (2FA) ─────────────────────────────────────────────────
+
+        /** 2FA 설정을 시작하고 QR 코드 / 시크릿을 반환합니다. */
+        twoFactorSetup(): Promise<{
+            ok: boolean;
+            setup_token: string;
+            qr_url: string;
+            secret: string;
+        }> {
+            return this._request("POST", "/v1/auth/2fa/setup");
+        }
+
+        /** TOTP 코드로 2FA 설정을 완료합니다. */
+        twoFactorSetupVerify(
+            code: string,
+            setupToken: string,
+        ): Promise<{ ok: boolean; recovery_codes: string[] }> {
+            return this._request("POST", "/v1/auth/2fa/setup/verify", {
+                code,
+                setup_token: setupToken,
+            });
+        }
+
+        /** 2FA를 비활성화합니다. */
+        twoFactorDisable(code: string): Promise<{ ok: boolean }> {
+            return this._request("DELETE", "/v1/auth/2fa", { code });
+        }
+
+        /** 2FA 활성화 여부를 조회합니다. */
+        twoFactorStatus(): Promise<{ ok: boolean; enabled: boolean }> {
+            return this._request("GET", "/v1/auth/2fa/status");
+        }
+
+        /** 임시 토큰으로 TOTP 코드를 검증하여 최종 JWT를 발급받습니다. */
+        twoFactorVerify(
+            twoFactorToken: string,
+            code: string,
+        ): Promise<{
+            ok: boolean;
+            access_token: string;
+            refresh_token: string;
+            expires_in: number;
+        }> {
+            return this._request(
+                "POST",
+                "/v1/auth/2fa/verify",
+                { two_factor_token: twoFactorToken, code },
+                false,
+            );
+        }
+
+        /** 복구 코드로 2FA를 우회하여 최종 JWT를 발급받습니다. */
+        twoFactorRecovery(
+            twoFactorToken: string,
+            recoveryCode: string,
+        ): Promise<{
+            ok: boolean;
+            access_token: string;
+            refresh_token: string;
+            expires_in: number;
+        }> {
+            return this._request(
+                "POST",
+                "/v1/auth/2fa/recovery",
+                {
+                    two_factor_token: twoFactorToken,
+                    recovery_code: recoveryCode,
+                },
+                false,
+            );
+        }
+
+        /** 복구 코드를 재생성합니다. */
+        twoFactorRegenerateRecovery(
+            code: string,
+        ): Promise<{ ok: boolean; recovery_codes: string[] }> {
+            return this._request("POST", "/v1/auth/2fa/recovery/regenerate", {
+                code,
+            });
+        }
+    };
+}

package/src/mixins/email.ts

@@ -0,0 +1,46 @@
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+
+export function EmailMixin<TBase extends GConstructor<EntityServerClientBase>>(
+    Base: TBase,
+) {
+    return class EmailMixinClass extends Base {
+        // ─── 이메일 인증 / 변경 ───────────────────────────────────────────────
+
+        /** 이메일 인증 코드 또는 링크를 발송합니다. */
+        emailVerificationSend(email: string): Promise<{ ok: boolean }> {
+            return this._request(
+                "POST",
+                "/v1/email/verification/send",
+                { email },
+                false,
+            );
+        }
+
+        /** 이메일 인증 코드를 확인합니다. */
+        emailVerificationConfirm(token: string): Promise<{ ok: boolean }> {
+            return this._request(
+                "POST",
+                "/v1/email/verification/confirm",
+                { token },
+                false,
+            );
+        }
+
+        /** 현재 계정의 이메일 인증 상태를 조회합니다. (JWT 필요) */
+        emailVerificationStatus(): Promise<{
+            ok: boolean;
+            verified: boolean;
+            email?: string;
+        }> {
+            return this._request("GET", "/v1/email/verification/status");
+        }
+
+        /** 이메일 주소를 변경합니다. (JWT + 인증 코드 필요) */
+        emailChange(newEmail: string, code?: string): Promise<{ ok: boolean }> {
+            return this._request("POST", "/v1/email/change", {
+                new_email: newEmail,
+                ...(code ? { code } : {}),
+            });
+        }
+    };
+}

package/src/mixins/entity.ts

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

@@ -0,0 +1,99 @@
+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}`;
+        }
+    };
+}

package/src/mixins/identity.ts

@@ -0,0 +1,35 @@
+import type { IdentityRequestOptions } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+
+export function IdentityMixin<
+    TBase extends GConstructor<EntityServerClientBase>,
+>(Base: TBase) {
+    return class IdentityMixinClass extends Base {
+        // ─── 본인인증 ─────────────────────────────────────────────────────────
+
+        /** 본인인증 요청을 생성합니다. */
+        identityRequest(
+            opts: IdentityRequestOptions,
+        ): Promise<{ ok: boolean; data: Record<string, unknown> }> {
+            return this._request("POST", "/v1/identity/request", opts);
+        }
+
+        /** 본인인증 결과를 조회합니다. */
+        identityResult(requestId: string): Promise<{
+            ok: boolean;
+            data: Record<string, unknown>;
+        }> {
+            return this._request("GET", `/v1/identity/result/${requestId}`);
+        }
+
+        /** CI 해시 중복 여부를 확인합니다. */
+        identityVerifyCI(ciHash: string): Promise<{
+            ok: boolean;
+            data: { exists: boolean; account_seq?: number };
+        }> {
+            return this._request("POST", "/v1/identity/verify-ci", {
+                ci_hash: ciHash,
+            });
+        }
+    };
+}