entity-server-client 0.2.5 → 0.3.0

package/src/EntityServerClient.ts

@@ -1,546 +1,28 @@
-import type {
-    EntityHistoryRecord,
-    EntityListParams,
-    EntityListResult,
-    EntityQueryRequest,
-    EntityServerClientOptions,
-    RegisterPushDeviceOptions,
-} from "./types";
-import { readEnv, buildQuery } from "./client/utils";
-import { derivePacketKey, parseRequestBody } from "./client/packet";
-import { entityRequest, type RequestOptions } from "./client/request";
-
-export class EntityServerClient {
-    private baseUrl: string;
-    private token: string;
-    private apiKey: string;
-    private hmacSecret: string;
-    private packetMagicLen: number;
-    private encryptRequests: boolean;
-    private activeTxId: string | null = null;
-
-    // 세션 유지 관련
-    private keepSession: boolean;
-    private refreshBuffer: number;
-    private onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
-    private onSessionExpired?: (error: Error) => void;
-    private _sessionRefreshToken: string | null = null;
-    private _refreshTimer: ReturnType<typeof setTimeout> | null = null;
-
-    // ─── 초기화 & 설정 ────────────────────────────────────────────────────────
-
-    /**
-     * EntityServerClient 인스턴스를 생성합니다.
-     *
-     * 기본값:
-     * - `baseUrl`: `VITE_ENTITY_SERVER_URL` 또는 `http://localhost:47200`
-     * - `packetMagicLen`: `VITE_ENTITY_SERVER_PACKET_MAGIC_LEN` 또는 `4`
-     */
-    constructor(options: EntityServerClientOptions = {}) {
-        const envBaseUrl = readEnv("VITE_ENTITY_SERVER_URL");
-        const envMagicLen = readEnv("VITE_ENTITY_SERVER_PACKET_MAGIC_LEN");
-
-        this.baseUrl = (
-            options.baseUrl ??
-            envBaseUrl ??
-            "http://localhost:47200"
-        ).replace(/\/$/, "");
-        this.token = options.token ?? "";
-        this.apiKey = options.apiKey ?? "";
-        this.hmacSecret = options.hmacSecret ?? "";
-        this.packetMagicLen =
-            options.packetMagicLen ?? (envMagicLen ? Number(envMagicLen) : 4);
-        this.encryptRequests = options.encryptRequests ?? false;
-        this.keepSession = options.keepSession ?? false;
-        this.refreshBuffer = options.refreshBuffer ?? 60;
-        this.onTokenRefreshed = options.onTokenRefreshed;
-        this.onSessionExpired = options.onSessionExpired;
-    }
-
-    /** baseUrl, token, packetMagicLen, encryptRequests 값을 런타임에 갱신합니다. */
-    configure(options: Partial<EntityServerClientOptions>): void {
-        if (options.baseUrl) this.baseUrl = options.baseUrl.replace(/\/$/, "");
-        if (typeof options.token === "string") this.token = options.token;
-        if (typeof options.packetMagicLen === "number")
-            this.packetMagicLen = options.packetMagicLen;
-        if (typeof options.encryptRequests === "boolean")
-            this.encryptRequests = options.encryptRequests;
-        if (typeof options.apiKey === "string") this.apiKey = options.apiKey;
-        if (typeof options.hmacSecret === "string")
-            this.hmacSecret = options.hmacSecret;
-        if (typeof options.keepSession === "boolean")
-            this.keepSession = options.keepSession;
-        if (typeof options.refreshBuffer === "number")
-            this.refreshBuffer = options.refreshBuffer;
-        if (options.onTokenRefreshed)
-            this.onTokenRefreshed = options.onTokenRefreshed;
-        if (options.onSessionExpired)
-            this.onSessionExpired = options.onSessionExpired;
-    }
-
-    /** 인증 요청에 사용할 JWT Access Token을 설정합니다. */
-    setToken(token: string): void {
-        this.token = token;
-    }
-
-    /** HMAC 인증용 API Key를 설정합니다. */
-    setApiKey(apiKey: string): void {
-        this.apiKey = apiKey;
-    }
-
-    /** HMAC 인증용 시크릿을 설정합니다. */
-    setHmacSecret(secret: string): void {
-        this.hmacSecret = secret;
-    }
-
-    /** 암호화 패킷 magic 길이(`packet_magic_len`)를 설정합니다. */
-    setPacketMagicLen(length: number): void {
-        this.packetMagicLen = length;
-    }
-
-    /** 현재 암호화 패킷 magic 길이를 반환합니다. */
-    getPacketMagicLen(): number {
-        return this.packetMagicLen;
-    }
-
-    // ─── 세션 유지 ────────────────────────────────────────────────────────────
-
-    /** @internal 자동 토큰 갱신 타이머를 시작합니다. */
-    private _scheduleKeepSession(
-        refreshToken: string,
-        expiresIn: number,
-    ): void {
-        this._clearRefreshTimer();
-        this._sessionRefreshToken = refreshToken;
-        const delayMs = Math.max((expiresIn - this.refreshBuffer) * 1000, 0);
-        this._refreshTimer = setTimeout(async () => {
-            if (!this._sessionRefreshToken) return;
-            try {
-                const result = await this.refreshToken(
-                    this._sessionRefreshToken,
-                );
-                this.onTokenRefreshed?.(result.access_token, result.expires_in);
-                this._scheduleKeepSession(
-                    this._sessionRefreshToken,
-                    result.expires_in,
-                );
-            } catch (err) {
-                this._clearRefreshTimer();
-                this.onSessionExpired?.(
-                    err instanceof Error ? err : new Error(String(err)),
-                );
-            }
-        }, delayMs);
-    }
-
-    /** @internal 자동 갱신 타이머를 정리합니다. */
-    private _clearRefreshTimer(): void {
-        if (this._refreshTimer !== null) {
-            clearTimeout(this._refreshTimer);
-            this._refreshTimer = null;
-        }
-    }
-
-    /**
-     * 세션 유지 타이머를 중지합니다.
-     * `logout()` 호출 시 자동으로 중지되며, 직접 호출이 필요한 경우는 드뭅니다.
-     */
-    stopKeepSession(): void {
-        this._clearRefreshTimer();
-        this._sessionRefreshToken = null;
-    }
-
-    // ─── 인증 ─────────────────────────────────────────────────────────────────
-
-    /**
-     * 서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
-     *
-     * 서버가 `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,
-            );
-        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);
-        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;
-    }
-
-    // ─── 트랜잭션 ─────────────────────────────────────────────────────────────
-
-    /** 트랜잭션을 시작하고 활성 트랜잭션 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}`,
-        );
-    }
-
-    // ─── 푸시 ─────────────────────────────────────────────────────────────────
-
-    /** 푸시 관련 엔티티로 payload를 전송(Submit)합니다. */
-    push(
-        pushEntity: string,
-        payload: Record<string, unknown>,
-        opts: { transactionId?: string } = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        return this.submit(pushEntity, payload, opts);
-    }
-
-    /** 푸시 로그 엔티티 목록을 조회합니다. */
-    pushLogList<T = unknown>(
-        params: EntityListParams = {},
-    ): Promise<{ ok: boolean; data: EntityListResult<T> }> {
-        return this.list<T>("push_log", params);
-    }
-
-    /** 계정의 푸시 디바이스를 등록합니다. */
-    registerPushDevice(
-        accountSeq: number,
-        deviceId: string,
-        pushToken: string,
-        opts: RegisterPushDeviceOptions = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        const {
-            platform,
-            deviceType,
-            browser,
-            browserVersion,
-            pushEnabled = true,
-            transactionId,
-        } = opts;
-        return this.submit(
-            "account_device",
-            {
-                id: deviceId,
-                account_seq: accountSeq,
-                push_token: pushToken,
-                push_enabled: pushEnabled,
-                ...(platform ? { platform } : {}),
-                ...(deviceType ? { device_type: deviceType } : {}),
-                ...(browser ? { browser } : {}),
-                ...(browserVersion ? { browser_version: browserVersion } : {}),
-            },
-            { transactionId },
-        );
-    }
-
-    /** 디바이스 레코드의 푸시 토큰을 갱신합니다. */
-    updatePushDeviceToken(
-        deviceSeq: number,
-        pushToken: string,
-        opts: { pushEnabled?: boolean; transactionId?: string } = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        const { pushEnabled = true, transactionId } = opts;
-        return this.submit(
-            "account_device",
-            {
-                seq: deviceSeq,
-                push_token: pushToken,
-                push_enabled: pushEnabled,
-            },
-            { transactionId },
-        );
-    }
-
-    /** 디바이스의 푸시 수신을 비활성화합니다. */
-    disablePushDevice(
-        deviceSeq: number,
-        opts: { transactionId?: string } = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        return this.submit(
-            "account_device",
-            { seq: deviceSeq, push_enabled: false },
-            { transactionId: opts.transactionId },
-        );
-    }
-
-    // ─── 요청 본문 파싱 ───────────────────────────────────────────────────────
-
-    /**
-     * 요청 바디를 파싱합니다.
-     * `application/octet-stream`이면 XChaCha20-Poly1305 복호화, 그 외는 JSON 파싱합니다.
-     *
-     * @param requireEncrypted `true`이면 암호화된 요청만 허용합니다.
-     */
-    readRequestBody<T = Record<string, unknown>>(
-        body: ArrayBuffer | Uint8Array | string | T | null | undefined,
-        contentType = "application/json",
-        requireEncrypted = false,
-    ): T {
-        const key = derivePacketKey(this.hmacSecret, this.token);
-        return parseRequestBody<T>(
-            body,
-            contentType,
-            requireEncrypted,
-            key,
-            this.packetMagicLen,
-        );
-    }
-
-    // ─── 내부 헬퍼 ───────────────────────────────────────────────────────────
-
-    private get _reqOpts(): RequestOptions {
-        return {
-            baseUrl: this.baseUrl,
-            token: this.token,
-            apiKey: this.apiKey,
-            hmacSecret: this.hmacSecret,
-            packetMagicLen: this.packetMagicLen,
-            encryptRequests: this.encryptRequests,
-        };
-    }
-
-    private request<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,
-        );
-    }
-}
+/**
+ * @file EntityServerClient.ts
+ * Mixin 패턴으로 구성된 EntityServerClient.
+ *
+ * 절(section)별 구현:
+ *   src/client/base.ts      — 상태·생성자·공통 헬퍼
+ *   src/mixins/auth.ts      — 인증 (로그인/로그아웃/me/트랜잭션 등)
+ *   src/mixins/entity.ts    — 트랜잭션 & 엔티티 CRUD
+ *   src/mixins/push.ts      — 푸시 디바이스 관리
+ *   src/mixins/smtp.ts      — SMTP 메일 발송
+ *   src/mixins/file.ts      — 파일 스토리지
+ *   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 { SmtpMixin } from "./mixins/smtp";
+import { FileMixin } from "./mixins/file";
+import { UtilsMixin } from "./mixins/utils";
+
+// ─── Composed class ───────────────────────────────────────────────────────────
+
+export class EntityServerClient extends UtilsMixin(
+    FileMixin(
+        SmtpMixin(PushMixin(EntityMixin(AuthMixin(EntityServerClientBase)))),
+    ),
+) {}