entity-server-client 0.2.6 → 0.3.1

package/dist/types.d.ts

@@ -1,329 +0,0 @@
-/**
- * 엔티티 목록 조회 파라미터입니다.
- *
- * ```ts
- * client.list("post", {
- *   page: 1, limit: 10,
- *   orderBy: "created_time", orderDir: "DESC",
- *   fields: ["seq", "title", "created_time"],
- *   conditions: { status: "active" },
- * });
- * ```
- */
-export interface EntityListParams {
-    /** 조회 페이지 번호. 기본값: `1` */
-    page?: number;
-    /** 페이지당 레코드 수. 기본값: `20` */
-    limit?: number;
-    /** 정렬 기준 필드명 */
-    orderBy?: string;
-    /** 정렬 방향. 기본값: `"ASC"` */
-    orderDir?: "ASC" | "DESC";
-    /**
-     * 반환할 필드 목록.
-     *
-     * - **미지정 (기본값)**: 엔티티의 인덱스 필드만 반환합니다.
-     *   복호화를 건너뛰기 때문에 **가장 빠릅니다**.
-     * - `["*"]`: 전체 필드 반환 (복호화 수행).
-     * - 필드명 목록: 해당 필드만 반환합니다.
-     *   엔티티 설정에 `index`로 선언된 필드만 지정 가능합니다.
-     *   존재하지 않는 필드명을 지정하면 서버 에러가 발생합니다.
-     * - `seq`, `created_time`, `updated_time`, `license_seq`는 필드에 관계없이 항상 포함됩니다.
-     *
-     * ```ts
-     * // 기본값 (인덱스 필드만, 가장 빠름)
-     * client.list("account")
-     * // 전체 필드
-     * client.list("account", { fields: ["*"] })
-     * // seq, name, email만
-     * client.list("account", { fields: ["seq", "name", "email"] })
-     * ```
-     */
-    fields?: string[];
-    /** 필터 조건. POST body로 전달됩니다. (예: `{ status: "active" }`) */
-    conditions?: Record<string, unknown>;
-}
-/**
- * `list()`, `history()` 응답의 `data` 필드 구조입니다.
- *
- * 서버는 항상 이 구조로 반환합니다:
- * ```json
- * { "ok": true, "data": { "items": [...], "total": 100, "page": 1, "limit": 20 } }
- * ```
- */
-export interface EntityListResult<T = unknown> {
-    items: T[];
-    /** 전체 레코드 수 */
-    total: number;
-    /** 현재 페이지 번호 */
-    page: number;
-    /** 페이지당 레코드 수 */
-    limit: number;
-}
-/**
- * `query()` 메서드에 전달하는 SQL 쿼리 요청입니다.
- *
- * - `sql`: SELECT 전용 SQL. 인덱스 테이블만 조회 가능하며 JOIN 지원.
- * - `params`: SQL 바인딩 파라미터 (`?` 플레이스홀더 대응).
- * - `limit`: 최대 반환 건수 (최대 1000. 미지정 시 서버 기본값 적용).
- *
- * ```ts
- * client.query("order", {
- *   sql: `SELECT o.seq, o.status, u.name
- *         FROM order o
- *         JOIN account u ON u.data_seq = o.account_seq
- *         WHERE o.status = ?`,
- *   params: ["pending"],
- *   limit: 100,
- * });
- * ```
- */
-export interface EntityQueryRequest {
-    sql: string;
-    params?: unknown[];
-    limit?: number;
-}
-/**
- * `history()` 응답의 개별 이력 레코드 구조입니다.
- *
- * - `action`: `"INSERT"` | `"UPDATE"` | `"DELETE_SOFT"` | `"DELETE_HARD"` | `"ROLLBACK"`
- * - `data_snapshot`: 변경 당시 엔티티 데이터 스냅샷
- */
-export interface EntityHistoryRecord<T = unknown> {
-    seq: number;
-    action: "INSERT" | "UPDATE" | "DELETE_SOFT" | "DELETE_HARD" | "ROLLBACK" | string;
-    data_snapshot: T | null;
-    changed_by: number | null;
-    changed_time: string;
-}
-export interface RegisterPushDeviceOptions {
-    platform?: string;
-    deviceType?: string;
-    browser?: string;
-    browserVersion?: string;
-    pushEnabled?: boolean;
-    transactionId?: string;
-}
-/** EntityServerClient 생성/설정 옵션입니다. */
-export interface EntityServerClientOptions {
-    baseUrl?: string;
-    token?: string;
-    /**
-     * `true`이면 인증된 POST/PUT 요청 바디를 XChaCha20-Poly1305로 암호화합니다.
-     *
-     * 서버의 `EnablePacketEncryption`이 활성화된 경우 필수로 설정해야 합니다.
-     * 로그인(`login()`)·토큰 갱신(`refreshToken()`)은 인증 전 요청이므로 자동으로 건너뜁니다.
-     *
-     * 기본값: `false`
-     */
-    encryptRequests?: boolean;
-    /**
-     * `true`이면 `login()` 성공 후 Access Token 만료 전에 자동으로 갱신(silent refresh)합니다.
-     * 갱신 시점은 `expires_in - refreshBuffer` 초입니다.
-     *
-     * 갱신 성공 시 `onTokenRefreshed`, 실패 시 `onSessionExpired` 콜백이 호출됩니다.
-     *
-     * 기본값: `false`
-     */
-    keepSession?: boolean;
-    /**
-     * 만료 몇 초 전에 자동 갱신을 시도할지 설정합니다.
-     *
-     * 예: `expires_in = 3600`, `refreshBuffer = 60` → 3540초 후 갱신
-     *
-     * 기본값: `60`
-     */
-    refreshBuffer?: number;
-    /**
-     * 자동 갱신 성공 시 호출되는 콜백입니다.
-     * 새 `access_token`과 `expires_in`이 전달됩니다.
-     * 앱은 이 콜백에서 localStorage 등에 토큰을 저장해야 합니다.
-     */
-    onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
-    /**
-     * 세션 유지 갱신 실패 시 호출되는 콜백입니다.
-     * refresh_token 만료 등으로 재발급이 불가능한 경우입니다.
-     * 앱은 이 콜백에서 로그인 페이지로 이동하는 등의 처리를 해야 합니다.
-     */
-    onSessionExpired?: (error: Error) => void;
-    /**
-     * HMAC 인증용 API Key (`X-API-Key` 헤더).
-     * `hmacSecret`과 함께 설정하면 HMAC 인증 모드로 동작합니다.
-     * **서버 사이드(Node.js 등) 전용. 브라우저에서는 사용하지 마세요.**
-     */
-    apiKey?: string;
-    /**
-     * HMAC 인증 시크릿. `apiKey`와 함께 설정하면 HMAC 인증 모드로 동작합니다.
-     *
-     * 패킷 암호화 키도 이 값에서 HKDF-SHA256으로 유도합니다:
-     * `key = HKDF-SHA256(hmac_secret, info="entity-server:packet-encryption", salt="entity-server:hkdf:v1")`
-     *
-     * **서버 사이드(Node.js 등) 전용. 브라우저에서는 사용하지 마세요.**
-     */
-    hmacSecret?: string;
-}
-/** `smtpSend()` 요청 파라미터입니다. */
-export interface SmtpSendRequest {
-    /** provider 식별자 (생략 시 기본 provider 사용) */
-    provider?: string;
-    from?: string;
-    to: string[];
-    cc?: string[];
-    bcc?: string[];
-    subject?: string;
-    body_text?: string;
-    body_html?: string;
-    /** 이메일 템플릿 이름 */
-    template_name?: string;
-    /** 템플릿 변수 */
-    template_data?: Record<string, unknown>;
-    /** 첨부 파일 seq 배열 */
-    attachments?: number[];
-    reply_to?: string;
-    ref_entity?: string;
-    ref_seq?: number;
-}
-/** `smsSend()` 요청 파라미터입니다. */
-export interface SmsSendRequest {
-    provider?: string;
-    sender?: string;
-    /** 수신자 전화번호 (필수) */
-    receiver: string;
-    /** 메시지 내용 (필수) */
-    content: string;
-    /** MMS 제목 (LMS/MMS 전용) */
-    subject?: string;
-    image_url?: string;
-    ref_entity?: string;
-    ref_seq?: number;
-}
-/** `pushSend()` 요청 파라미터 (`POST /v1/push/send`) */
-export interface PushSendRequest {
-    /** 수신 계정 seq 배열 (필수) */
-    account_seqs: number[];
-    title: string;
-    body: string;
-    /** 커스텀 페이로드 */
-    data?: Record<string, string>;
-    ref_entity?: string;
-    ref_seq?: number;
-}
-/** `pushSendAll()` 요청 파라미터 (`POST /v1/push/send-all`) */
-export interface PushSendAllRequest {
-    title: string;
-    body: string;
-    data?: Record<string, string>;
-    ref_entity?: string;
-    ref_seq?: number;
-}
-/** 알림톡 / 친구톡 버튼 */
-export interface AlimtalkButton {
-    name: string;
-    type: string;
-    url_mobile?: string;
-    url_pc?: string;
-}
-/** `alimtalkSend()` 요청 파라미터 */
-export interface AlimtalkSendRequest {
-    /** 알림톡 템플릿 코드 (필수) */
-    template_code: string;
-    /** 수신자 전화번호 (필수) */
-    receiver: string;
-    variables?: Record<string, string>;
-    provider?: string;
-}
-/** `friendtalkSend()` 요청 파라미터 */
-export interface FriendtalkSendRequest {
-    /** 수신자 전화번호 (필수) */
-    receiver: string;
-    /** 메시지 내용 (필수) */
-    content: string;
-    /** 메시지 타입 (`"text"` | `"image"` | `"wide_image"` 등, 기본 `"text"`) */
-    msg_type?: string;
-    image_url?: string;
-    image_link?: string;
-    /** 광고 여부 (기본 `true`) */
-    is_ad?: boolean;
-    buttons?: AlimtalkButton[];
-    carousel_json?: string;
-    items_json?: string;
-    header?: string;
-    provider?: string;
-}
-/** `pgCreateOrder()` 요청 파라미터 */
-export interface PgCreateOrderRequest {
-    /** 결제 금액 (필수) */
-    amount: number;
-    /** 주문명 (필수) */
-    order_name: string;
-    currency?: string;
-    customer_name?: string;
-    customer_email?: string;
-    provider?: string;
-    metadata?: Record<string, unknown>;
-}
-/** `pgConfirmPayment()` 요청 파라미터 */
-export interface PgConfirmPaymentRequest {
-    payment_key: string;
-    order_id: string;
-    amount: number;
-}
-/** `pgCancelPayment()` 요청 파라미터 */
-export interface PgCancelPaymentRequest {
-    /** 취소 사유 (필수) */
-    cancel_reason: string;
-    /** 부분 취소 금액 (생략 시 전액 취소) */
-    cancel_amount?: number;
-    refund_account?: {
-        bank: string;
-        account_number: string;
-        holder_name: string;
-    };
-}
-/** `identityRequest()` 요청 파라미터 */
-export interface IdentityRequestOptions {
-    /** 인증 목적 (필수, 예: `"signup"`, `"password_reset"`) */
-    purpose: string;
-    /** 인증 방법 (예: `"simple"`, `"pass"`) */
-    method?: string;
-    provider?: string;
-}
-/** `qrcode()` / `qrcodeBase64()` / `qrcodeText()` 공통 옵션 */
-export interface QRCodeOptions {
-    /** PNG 크기 픽셀 (기본 256, 최대 2048) */
-    size?: number;
-    /** 오류 복구 수준 (기본 `"medium"`) */
-    error_correction?: "low" | "medium" | "high" | "highest";
-    /** 전경색 hex (기본 `"#000000"`) */
-    fg_color?: string;
-    /** 배경색 hex (기본 `"#ffffff"`) */
-    bg_color?: string;
-}
-/** `barcode()` 옵션 */
-export interface BarcodeOptions {
-    /** 바코드 타입 (기본 `"code128"`) */
-    type?: "code128" | "code39" | "ean13" | "ean8" | "codabar" | "datamatrix" | "itf";
-    /** 너비 픽셀 (기본 300, 최대 2048) */
-    width?: number;
-    /** 높이 픽셀 (기본 100, 최대 2048) */
-    height?: number;
-}
-/** 파일 메타 정보 */
-export interface FileMeta {
-    uuid: string;
-    original_name: string;
-    size: number;
-    mime_type: string;
-    entity: string;
-    ref_seq?: number;
-    is_public?: boolean;
-    created_time: string;
-    url?: string;
-}
-/** `fileUpload()` 옵션 */
-export interface FileUploadOptions {
-    /** 파일에 연결할 ref_seq */
-    refSeq?: number;
-    /** 공개 파일 여부 (기본 서버 설정 따름) */
-    isPublic?: boolean;
-}

package/src/mixins/alimtalk.ts

@@ -1,35 +0,0 @@
-import type { AlimtalkSendRequest, FriendtalkSendRequest } from "../types";
-import type { GConstructor, EntityServerClientBase } from "../client/base";
-
-export function AlimtalkMixin<
-    TBase extends GConstructor<EntityServerClientBase>,
->(Base: TBase) {
-    return class AlimtalkMixinClass extends Base {
-        // ─── 알림톡 / 친구톡 ─────────────────────────────────────────────────
-
-        /** 알림톡(KakaoTalk 비즈 메시지)을 발송합니다. */
-        alimtalkSend(req: AlimtalkSendRequest): Promise<{ message: string }> {
-            return this._request("POST", "/v1/alimtalk/send", req);
-        }
-
-        /** 알림톡 발송 상태를 조회합니다. */
-        alimtalkStatus(seq: number): Promise<{ ok: boolean; status: string }> {
-            return this._request("GET", `/v1/alimtalk/status/${seq}`);
-        }
-
-        /** 사용 가능한 알림톡 템플릿 목록을 조회합니다. */
-        alimtalkTemplates(): Promise<{
-            templates: Array<{ code: string; name: string; content: string }>;
-            count: number;
-        }> {
-            return this._request("GET", "/v1/alimtalk/templates");
-        }
-
-        /** 친구톡(KakaoTalk 채널 메시지)을 발송합니다. */
-        friendtalkSend(
-            req: FriendtalkSendRequest,
-        ): Promise<{ message: string }> {
-            return this._request("POST", "/v1/friendtalk/send", req);
-        }
-    };
-}

package/src/mixins/email.ts

@@ -1,46 +0,0 @@
-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/identity.ts

@@ -1,35 +0,0 @@
-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,
-            });
-        }
-    };
-}

package/src/mixins/pg.ts

@@ -1,58 +0,0 @@
-import type {
-    PgCreateOrderRequest,
-    PgConfirmPaymentRequest,
-    PgCancelPaymentRequest,
-} from "../types";
-import type { GConstructor, EntityServerClientBase } from "../client/base";
-
-export function PgMixin<TBase extends GConstructor<EntityServerClientBase>>(
-    Base: TBase,
-) {
-    return class PgMixinClass extends Base {
-        // ─── PG(결제 게이트웨이) ──────────────────────────────────────────────
-
-        /** 결제 주문을 생성합니다. */
-        pgCreateOrder(
-            req: PgCreateOrderRequest,
-        ): Promise<{ ok: boolean; data: Record<string, unknown> }> {
-            return this._request("POST", "/v1/pg/orders", req);
-        }
-
-        /** 주문 정보를 조회합니다. */
-        pgGetOrder(orderId: string): Promise<{
-            ok: boolean;
-            data: Record<string, unknown>;
-        }> {
-            return this._request("GET", `/v1/pg/orders/${orderId}`);
-        }
-
-        /** 결제를 승인합니다. */
-        pgConfirmPayment(
-            req: PgConfirmPaymentRequest,
-        ): Promise<{ ok: boolean; data: Record<string, unknown> }> {
-            return this._request("POST", "/v1/pg/confirm", req);
-        }
-
-        /** 결제를 취소합니다. */
-        pgCancelPayment(
-            orderId: string,
-            req: PgCancelPaymentRequest,
-        ): Promise<{ ok: boolean; data: Record<string, unknown> }> {
-            return this._request(
-                "POST",
-                `/v1/pg/orders/${orderId}/cancel`,
-                req,
-            );
-        }
-
-        /** 결제 상태를 외부 PG와 동기화합니다. */
-        pgSyncPayment(orderId: string): Promise<{ ok: boolean }> {
-            return this._request("POST", `/v1/pg/orders/${orderId}/sync`, {});
-        }
-
-        /** 클라이언트 SDK 설정을 반환합니다 (공개 API, 인증 불필요). */
-        pgConfig(): Promise<{ ok: boolean; data: Record<string, unknown> }> {
-            return this._request("GET", "/v1/pg/config", undefined, false);
-        }
-    };
-}

package/src/mixins/sms.ts

@@ -1,46 +0,0 @@
-import type { SmsSendRequest } from "../types";
-import type { GConstructor, EntityServerClientBase } from "../client/base";
-
-export function SmsMixin<TBase extends GConstructor<EntityServerClientBase>>(
-    Base: TBase,
-) {
-    return class SmsMixinClass extends Base {
-        // ─── SMS 발송 / 인증 ──────────────────────────────────────────────────
-
-        /** SMS를 발송합니다. */
-        smsSend(req: SmsSendRequest): Promise<{ ok: boolean; seq: number }> {
-            return this._request("POST", "/v1/sms/send", req);
-        }
-
-        /** SMS 발송 상태를 조회합니다. */
-        smsStatus(seq: number): Promise<{ ok: boolean; status: string }> {
-            return this._request("GET", `/v1/sms/status/${seq}`);
-        }
-
-        /** SMS 인증 코드를 발송합니다. */
-        smsVerificationSend(
-            phone: string,
-            opts: { purpose?: string } = {},
-        ): Promise<{ ok: boolean }> {
-            return this._request(
-                "POST",
-                "/v1/sms/verification/send",
-                { phone, ...opts },
-                false,
-            );
-        }
-
-        /** SMS 인증 코드를 검증합니다. */
-        smsVerificationVerify(
-            phone: string,
-            code: string,
-        ): Promise<{ ok: boolean; verified: boolean }> {
-            return this._request(
-                "POST",
-                "/v1/sms/verification/verify",
-                { phone, code },
-                false,
-            );
-        }
-    };
-}