entity-server-client 0.2.5 → 0.2.6

package/src/mixins/pg.ts

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

@@ -0,0 +1,132 @@
+import type {
+    EntityListParams,
+    EntityListResult,
+    RegisterPushDeviceOptions,
+    PushSendRequest,
+    PushSendAllRequest,
+} 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 },
+            );
+        }
+
+        // ─── 푸시 발송 API ────────────────────────────────────────────────────
+
+        /** 특정 계정에 푸시 알림을 발송합니다. */
+        pushSend(req: PushSendRequest): Promise<{ ok: boolean; seq: number }> {
+            return this._request("POST", "/v1/push/send", req);
+        }
+
+        /** 전체 사용자에게 푸시 알림을 발송합니다. */
+        pushSendAll(req: PushSendAllRequest): Promise<{
+            ok: boolean;
+            sent: number;
+            failed: number;
+        }> {
+            return this._request("POST", "/v1/push/send-all", req);
+        }
+
+        /** 푸시 발송 상태를 조회합니다. */
+        pushStatus(seq: number): Promise<{ ok: boolean; status: string }> {
+            return this._request("POST", `/v1/push/status/${seq}`, {});
+        }
+    };
+}

package/src/mixins/sms.ts

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

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,75 @@
+import type { QRCodeOptions, BarcodeOptions } 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,
+            });
+        }
+    };
+}

package/src/types.ts

@@ -129,7 +129,6 @@ export interface RegisterPushDeviceOptions {
 export interface EntityServerClientOptions {
     baseUrl?: string;
     token?: string;
-    packetMagicLen?: number;
     /**
      * `true`이면 인증된 POST/PUT 요청 바디를 XChaCha20-Poly1305로 암호화합니다.
      *
@@ -184,3 +183,206 @@ export interface EntityServerClientOptions {
      */
     hmacSecret?: string;
 }
+
+// ─── SMTP ─────────────────────────────────────────────────────────────────────
+
+/** `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;
+}
+
+// ─── SMS ──────────────────────────────────────────────────────────────────────
+
+/** `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;
+}
+
+// ─── Push 발송 API ──────────────────────────────────────────────────────────────
+
+/** `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;
+}
+
+// ─── PG 결제 ──────────────────────────────────────────────────────────────────
+
+/** `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;
+}
+
+// ─── Utils ────────────────────────────────────────────────────────────────────
+
+/** `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;
+}