entity-server-client 0.2.5 → 0.3.0

package/src/mixins/auth.ts

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

@@ -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/push.ts

@@ -0,0 +1,109 @@
+import type {
+    EntityListParams,
+    EntityListResult,
+    RegisterPushDeviceOptions,
+} from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+
+// entity submit을 가진 base 타입 (EntityMixin 적용 후)
+type WithSubmit = EntityServerClientBase & {
+    submit(
+        entity: string,
+        data: Record<string, unknown>,
+        opts?: { transactionId?: string; skipHooks?: boolean },
+    ): Promise<{ ok: boolean; seq: number }>;
+    list<T = unknown>(
+        entity: string,
+        params?: EntityListParams,
+    ): Promise<{ ok: boolean; data: EntityListResult<T> }>;
+};
+
+export function PushMixin<TBase extends GConstructor<WithSubmit>>(Base: TBase) {
+    return class PushMixinClass extends Base {
+        // ─── 푸시 submit 래퍼 ────────────────────────────────────────────────
+
+        /**
+         * 푸시 관련 엔티티로 payload를 전송(Submit)합니다.
+         * 내부적으로 `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 },
+            );
+        }
+    };
+}

package/src/mixins/smtp.ts

@@ -0,0 +1,20 @@
+import type { SmtpSendRequest } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+
+export function SmtpMixin<TBase extends GConstructor<EntityServerClientBase>>(
+    Base: TBase,
+) {
+    return class SmtpMixinClass extends Base {
+        // ─── SMTP 메일 발송 ───────────────────────────────────────────────────
+
+        /** SMTP로 메일을 발송합니다. */
+        smtpSend(req: SmtpSendRequest): Promise<{ ok: boolean; seq: number }> {
+            return this._request("POST", "/v1/smtp/send", req);
+        }
+
+        /** SMTP 발송 상태를 조회합니다. */
+        smtpStatus(seq: number): Promise<{ ok: boolean; status: string }> {
+            return this._request("POST", `/v1/smtp/status/${seq}`, {});
+        }
+    };
+}

package/src/mixins/utils.ts

@@ -0,0 +1,106 @@
+import type { QRCodeOptions, BarcodeOptions, Pdf2PngOptions } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+
+export function UtilsMixin<TBase extends GConstructor<EntityServerClientBase>>(
+    Base: TBase,
+) {
+    return class UtilsMixinClass extends Base {
+        // ─── Utils (QR / 바코드) ──────────────────────────────────────────────
+
+        /**
+         * QR 코드 PNG를 생성합니다. `ArrayBuffer`를 반환합니다.
+         *
+         * ```ts
+         * const buf = await client.qrcode("https://example.com");
+         * const blob = new Blob([buf], { type: "image/png" });
+         * img.src = URL.createObjectURL(blob);
+         * ```
+         */
+        qrcode(
+            content: string,
+            opts: QRCodeOptions = {},
+        ): Promise<ArrayBuffer> {
+            return this._requestBinary("POST", "/v1/utils/qrcode", {
+                content,
+                ...opts,
+            });
+        }
+
+        /**
+         * QR 코드를 base64/data URI JSON으로 반환합니다.
+         *
+         * ```ts
+         * const { data_uri } = await client.qrcodeBase64("https://example.com");
+         * img.src = data_uri;
+         * ```
+         */
+        qrcodeBase64(
+            content: string,
+            opts: QRCodeOptions = {},
+        ): Promise<{ ok: boolean; data: string; data_uri: string }> {
+            return this._request("POST", "/v1/utils/qrcode/base64", {
+                content,
+                ...opts,
+            });
+        }
+
+        /** QR 코드를 ASCII 아트 텍스트로 반환합니다. */
+        qrcodeText(
+            content: string,
+            opts: QRCodeOptions = {},
+        ): Promise<{ ok: boolean; text: string }> {
+            return this._request("POST", "/v1/utils/qrcode/text", {
+                content,
+                ...opts,
+            });
+        }
+
+        /**
+         * 바코드 PNG를 생성합니다. `ArrayBuffer`를 반환합니다.
+         *
+         * ```ts
+         * const buf = await client.barcode("1234567890128", { type: "ean13" });
+         * ```
+         */
+        barcode(
+            content: string,
+            opts: BarcodeOptions = {},
+        ): Promise<ArrayBuffer> {
+            return this._requestBinary("POST", "/v1/utils/barcode", {
+                content,
+                ...opts,
+            });
+        }
+
+        /**
+         * PDF를 PNG 이미지로 변환합니다.
+         *
+         * 단일 페이지 요청이면 `image/png` ArrayBuffer,
+         * 다중 페이지 요청이면 `application/zip` ArrayBuffer를 반환합니다.
+         *
+         * ```ts
+         * const buf = await client.pdf2png(pdfArrayBuffer, { dpi: 200 });
+         * ```
+         */
+        pdf2png(
+            pdfData: ArrayBuffer | Uint8Array<ArrayBuffer>,
+            opts: Pdf2PngOptions = {},
+        ): Promise<ArrayBuffer> {
+            const form = new FormData();
+            form.append(
+                "file",
+                new Blob([pdfData], { type: "application/pdf" }),
+                "document.pdf",
+            );
+            const params = new URLSearchParams();
+            if (opts.dpi != null) params.set("dpi", String(opts.dpi));
+            if (opts.firstPage != null)
+                params.set("first_page", String(opts.firstPage));
+            if (opts.lastPage != null)
+                params.set("last_page", String(opts.lastPage));
+            const qs = params.toString();
+            const path = "/v1/utils/pdf2png" + (qs ? `?${qs}` : "");
+            return this._requestFormBinary("POST", path, form);
+        }
+    };
+}