entity-server-client 0.3.2 → 1.0.0

package/dist/mixins/file.d.ts

@@ -0,0 +1,85 @@
+import type { FileMeta, FileUploadOptions } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+export declare function FileMixin<TBase extends GConstructor<EntityServerClientBase>>(Base: TBase): {
+    new (...args: any[]): {
+        /**
+         * 파일을 업로드합니다. (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);
+         * ```
+         */
+        fileUpload(entity: string, file: File | Blob, opts?: FileUploadOptions): Promise<{
+            ok: boolean;
+            uuid: string;
+            data: FileMeta;
+        }>;
+        /** 파일을 다운로드합니다. `ArrayBuffer`를 반환합니다. */
+        fileDownload(entity: string, uuid: string): Promise<ArrayBuffer>;
+        /** 파일을 삭제합니다. */
+        fileDelete(entity: string, uuid: string): Promise<{
+            ok: boolean;
+            uuid: string;
+            deleted: boolean;
+        }>;
+        /** 엔티티에 연결된 파일 목록을 조회합니다. */
+        fileList(entity: string, opts?: {
+            refSeq?: number;
+        }): Promise<{
+            ok: boolean;
+            data: {
+                items: FileMeta[];
+                total: number;
+            };
+        }>;
+        /** 파일 메타 정보를 조회합니다. */
+        fileMeta(entity: string, uuid: string): Promise<{
+            ok: boolean;
+            data: FileMeta;
+        }>;
+        /** 임시 파일 접근 토큰을 발급합니다. */
+        fileToken(uuid: string): Promise<{
+            ok: boolean;
+            token: string;
+        }>;
+        /** 파일 인라인 뷰 URL을 반환합니다. (fetch 없음, URL 조합만) */
+        fileUrl(uuid: string): string;
+        baseUrl: string;
+        token: string;
+        anonymousPacketToken: string;
+        apiKey: string;
+        hmacSecret: string;
+        encryptRequests: boolean;
+        activeTxId: string | null;
+        keepSession: boolean;
+        refreshBuffer: number;
+        onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+        onSessionExpired?: (error: Error) => void;
+        _sessionRefreshToken: string | null;
+        _refreshTimer: ReturnType<typeof setTimeout> | null;
+        configure(options: Partial<import("..").EntityServerClientOptions>): void;
+        setToken(token: string): void;
+        setAnonymousPacketToken(token: string): void;
+        setApiKey(apiKey: string): void;
+        setHmacSecret(secret: string): void;
+        setEncryptRequests(value: boolean): void;
+        _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+            access_token: string;
+            expires_in: number;
+        }>): void;
+        _clearRefreshTimer(): void;
+        stopKeepSession(): void;
+        readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+        get _reqOpts(): import("../client/request").RequestOptions;
+        requestJson<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+        requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+        _request<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+        _requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+    };
+} & TBase;

package/dist/mixins/identity.d.ts

@@ -0,0 +1,52 @@
+import type { IdentityRequestOptions } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+export declare function IdentityMixin<TBase extends GConstructor<EntityServerClientBase>>(Base: TBase): {
+    new (...args: any[]): {
+        /** 본인인증 요청을 생성합니다. */
+        identityRequest(opts: IdentityRequestOptions): Promise<{
+            ok: boolean;
+            data: Record<string, unknown>;
+        }>;
+        /** 본인인증 결과를 조회합니다. */
+        identityResult(requestId: string): Promise<{
+            ok: boolean;
+            data: Record<string, unknown>;
+        }>;
+        /** CI 해시 중복 여부를 확인합니다. */
+        identityVerifyCI(ciHash: string): Promise<{
+            ok: boolean;
+            data: {
+                exists: boolean;
+                account_seq?: number;
+            };
+        }>;
+        baseUrl: string;
+        token: string;
+        apiKey: string;
+        hmacSecret: string;
+        encryptRequests: boolean;
+        activeTxId: string | null;
+        keepSession: boolean;
+        refreshBuffer: number;
+        onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+        onSessionExpired?: (error: Error) => void;
+        _sessionRefreshToken: string | null;
+        _refreshTimer: ReturnType<typeof setTimeout> | null;
+        configure(options: Partial<import("..").EntityServerClientOptions>): void;
+        setToken(token: string): void;
+        setApiKey(apiKey: string): void;
+        setHmacSecret(secret: string): void;
+        setEncryptRequests(value: boolean): void;
+        _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+            access_token: string;
+            expires_in: number;
+        }>): void;
+        _clearRefreshTimer(): void;
+        stopKeepSession(): void;
+        readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+        get _reqOpts(): import("../client/request").RequestOptions;
+        _request<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+    };
+} & TBase;

package/dist/mixins/llm.d.ts

@@ -0,0 +1,94 @@
+/**
+ * LlmMixin — LLM API 클라이언트 Mixin
+ *
+ * 설계문서 Section 14 기준 구현.
+ */
+import type { LlmChatRequest, LlmChatResponse, LlmConversationCreateRequest, LlmConversationDetail, LlmConversationListResponse, LlmConversationUpdateRequest, LlmDocumentIngestRequest, LlmDocumentIngestResponse, LlmDocumentListResponse, LlmProvidersResponse, LlmRAGChatRequest, LlmRAGSearchRequest, LlmRAGSearchResponse, LlmUsageResponse, LlmUsageSummaryResponse, LlmCacheStats } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+export declare function LlmMixin<TBase extends GConstructor<EntityServerClientBase>>(Base: TBase): {
+    new (...args: any[]): {
+        /** SSE/스트리밍 응답을 위한 raw fetch — Response 객체 반환 */
+        _llmStream(path: string, body: unknown): Promise<Response>;
+        llmChat(req: LlmChatRequest): Promise<LlmChatResponse>;
+        llmChatStream(req: LlmChatRequest): Promise<Response>;
+        llmCreateConversation(req: LlmConversationCreateRequest): Promise<{
+            ok: boolean;
+            data: {
+                seq: number;
+            };
+        }>;
+        llmSendMessage(seq: number, req: LlmChatRequest): Promise<LlmChatResponse>;
+        llmListConversations(params?: {
+            page?: number;
+            limit?: number;
+            user_seq?: number;
+        }): Promise<LlmConversationListResponse>;
+        llmGetConversation(seq: number): Promise<LlmConversationDetail>;
+        llmUpdateConversation(seq: number, req: LlmConversationUpdateRequest): Promise<{
+            ok: boolean;
+        }>;
+        llmDeleteConversation(seq: number): Promise<{
+            ok: boolean;
+        }>;
+        llmGetProviders(): Promise<LlmProvidersResponse>;
+        llmGetUsage(params?: {
+            provider?: string;
+            start_date?: string;
+            end_date?: string;
+        }): Promise<LlmUsageResponse>;
+        llmGetUsageSummary(params?: {
+            provider?: string;
+            start_date?: string;
+            end_date?: string;
+        }): Promise<LlmUsageSummaryResponse>;
+        llmIngestDocument(req: LlmDocumentIngestRequest): Promise<LlmDocumentIngestResponse>;
+        llmListDocuments(params?: {
+            page?: number;
+            limit?: number;
+        }): Promise<LlmDocumentListResponse>;
+        llmDeleteDocument(id: string): Promise<{
+            ok: boolean;
+        }>;
+        llmSearchDocuments(req: LlmRAGSearchRequest): Promise<LlmRAGSearchResponse>;
+        llmChatWithRAG(req: LlmRAGChatRequest): Promise<LlmChatResponse>;
+        llmChatWithRAGStream(req: LlmRAGChatRequest): Promise<Response>;
+        llmRebuildRAGIndex(): Promise<{
+            ok: boolean;
+        }>;
+        llmGetCacheStats(): Promise<{
+            ok: boolean;
+            data: LlmCacheStats;
+        }>;
+        llmClearCache(): Promise<{
+            ok: boolean;
+        }>;
+        baseUrl: string;
+        token: string;
+        apiKey: string;
+        hmacSecret: string;
+        encryptRequests: boolean;
+        activeTxId: string | null;
+        keepSession: boolean;
+        refreshBuffer: number;
+        onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+        onSessionExpired?: (error: Error) => void;
+        _sessionRefreshToken: string | null;
+        _refreshTimer: ReturnType<typeof setTimeout> | null;
+        configure(options: Partial<import("..").EntityServerClientOptions>): void;
+        setToken(token: string): void;
+        setApiKey(apiKey: string): void;
+        setHmacSecret(secret: string): void;
+        setEncryptRequests(value: boolean): void;
+        _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+            access_token: string;
+            expires_in: number;
+        }>): void;
+        _clearRefreshTimer(): void;
+        stopKeepSession(): void;
+        readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+        get _reqOpts(): import("../client/request").RequestOptions;
+        _request<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+    };
+} & TBase;

package/dist/mixins/pg.d.ts

@@ -0,0 +1,63 @@
+import type { PgCreateOrderRequest, PgConfirmPaymentRequest, PgCancelPaymentRequest } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+export declare function PgMixin<TBase extends GConstructor<EntityServerClientBase>>(Base: TBase): {
+    new (...args: any[]): {
+        /** 결제 주문을 생성합니다. */
+        pgCreateOrder(req: PgCreateOrderRequest): Promise<{
+            ok: boolean;
+            data: Record<string, unknown>;
+        }>;
+        /** 주문 정보를 조회합니다. */
+        pgGetOrder(orderId: string): Promise<{
+            ok: boolean;
+            data: Record<string, unknown>;
+        }>;
+        /** 결제를 승인합니다. */
+        pgConfirmPayment(req: PgConfirmPaymentRequest): Promise<{
+            ok: boolean;
+            data: Record<string, unknown>;
+        }>;
+        /** 결제를 취소합니다. */
+        pgCancelPayment(orderId: string, req: PgCancelPaymentRequest): Promise<{
+            ok: boolean;
+            data: Record<string, unknown>;
+        }>;
+        /** 결제 상태를 외부 PG와 동기화합니다. */
+        pgSyncPayment(orderId: string): Promise<{
+            ok: boolean;
+        }>;
+        /** 클라이언트 SDK 설정을 반환합니다 (공개 API, 인증 불필요). */
+        pgConfig(): Promise<{
+            ok: boolean;
+            data: Record<string, unknown>;
+        }>;
+        baseUrl: string;
+        token: string;
+        apiKey: string;
+        hmacSecret: string;
+        encryptRequests: boolean;
+        activeTxId: string | null;
+        keepSession: boolean;
+        refreshBuffer: number;
+        onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+        onSessionExpired?: (error: Error) => void;
+        _sessionRefreshToken: string | null;
+        _refreshTimer: ReturnType<typeof setTimeout> | null;
+        configure(options: Partial<import("..").EntityServerClientOptions>): void;
+        setToken(token: string): void;
+        setApiKey(apiKey: string): void;
+        setHmacSecret(secret: string): void;
+        setEncryptRequests(value: boolean): void;
+        _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+            access_token: string;
+            expires_in: number;
+        }>): void;
+        _clearRefreshTimer(): void;
+        stopKeepSession(): void;
+        readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+        get _reqOpts(): import("../client/request").RequestOptions;
+        _request<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+    };
+} & TBase;

package/dist/mixins/push.d.ts

@@ -0,0 +1,101 @@
+import type { EntityListParams, EntityListResult, RegisterPushDeviceOptions } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+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 declare function PushMixin<TBase extends GConstructor<WithSubmit>>(Base: TBase): {
+    new (...args: any[]): {
+        /**
+         * 푸시 관련 엔티티로 payload를 전송(Submit)합니다.
+         * 내부적으로 `submit()` 메서드를 호출합니다.
+         */
+        push(pushEntity: string, payload: Record<string, unknown>, opts?: {
+            transactionId?: string;
+        }): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        /** 푸시 로그 엔티티 목록을 조회합니다. */
+        pushLogList<T = unknown>(params?: EntityListParams): Promise<{
+            ok: boolean;
+            data: EntityListResult<T>;
+        }>;
+        /** 계정의 푸시 디바이스를 등록합니다. */
+        registerPushDevice(accountSeq: number, deviceId: string, pushToken: string, opts?: RegisterPushDeviceOptions): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        /** 디바이스 레코드의 푸시 토큰을 갱신합니다. */
+        updatePushDeviceToken(deviceSeq: number, pushToken: string, opts?: {
+            pushEnabled?: boolean;
+            transactionId?: string;
+        }): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        /** 디바이스의 푸시 수신을 비활성화합니다. */
+        disablePushDevice(deviceSeq: number, opts?: {
+            transactionId?: string;
+        }): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        baseUrl: string;
+        token: string;
+        anonymousPacketToken: string;
+        apiKey: string;
+        hmacSecret: string;
+        encryptRequests: boolean;
+        activeTxId: string | null;
+        keepSession: boolean;
+        refreshBuffer: number;
+        onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+        onSessionExpired?: (error: Error) => void;
+        _sessionRefreshToken: string | null;
+        _refreshTimer: ReturnType<typeof setTimeout> | null;
+        configure(options: Partial<import("..").EntityServerClientOptions>): void;
+        setToken(token: string): void;
+        setAnonymousPacketToken(token: string): void;
+        setApiKey(apiKey: string): void;
+        setHmacSecret(secret: string): void;
+        setEncryptRequests(value: boolean): void;
+        _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+            access_token: string;
+            expires_in: number;
+        }>): void;
+        _clearRefreshTimer(): void;
+        stopKeepSession(): void;
+        readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+        get _reqOpts(): import("../client/request").RequestOptions;
+        requestJson<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+        requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+        _request<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+        _requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+        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>;
+        }>;
+    };
+} & TBase;
+export {};

package/dist/mixins/sms.d.ts

@@ -0,0 +1,55 @@
+import type { SmsSendRequest } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+export declare function SmsMixin<TBase extends GConstructor<EntityServerClientBase>>(Base: TBase): {
+    new (...args: any[]): {
+        /** SMS를 발송합니다. */
+        smsSend(req: SmsSendRequest): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        /** SMS 발송 상태를 조회합니다. */
+        smsStatus(seq: number): Promise<{
+            ok: boolean;
+            status: string;
+        }>;
+        /** SMS 인증 코드를 발송합니다. */
+        smsVerificationSend(phone: string, opts?: {
+            purpose?: string;
+        }): Promise<{
+            ok: boolean;
+        }>;
+        /** SMS 인증 코드를 검증합니다. */
+        smsVerificationVerify(phone: string, code: string): Promise<{
+            ok: boolean;
+            verified: boolean;
+        }>;
+        baseUrl: string;
+        token: string;
+        apiKey: string;
+        hmacSecret: string;
+        encryptRequests: boolean;
+        activeTxId: string | null;
+        keepSession: boolean;
+        refreshBuffer: number;
+        onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+        onSessionExpired?: (error: Error) => void;
+        _sessionRefreshToken: string | null;
+        _refreshTimer: ReturnType<typeof setTimeout> | null;
+        configure(options: Partial<import("..").EntityServerClientOptions>): void;
+        setToken(token: string): void;
+        setApiKey(apiKey: string): void;
+        setHmacSecret(secret: string): void;
+        setEncryptRequests(value: boolean): void;
+        _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+            access_token: string;
+            expires_in: number;
+        }>): void;
+        _clearRefreshTimer(): void;
+        stopKeepSession(): void;
+        readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+        get _reqOpts(): import("../client/request").RequestOptions;
+        _request<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+    };
+} & TBase;

package/dist/mixins/smtp.d.ts

@@ -0,0 +1,51 @@
+import type { SmtpSendRequest } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+export declare function SmtpMixin<TBase extends GConstructor<EntityServerClientBase>>(Base: TBase): {
+    new (...args: any[]): {
+        /** SMTP로 메일을 발송합니다. */
+        smtpSend(req: SmtpSendRequest): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        /** SMTP 발송 상태를 조회합니다. */
+        smtpStatus(seq: number): Promise<{
+            ok: boolean;
+            status: string;
+        }>;
+        baseUrl: string;
+        token: string;
+        anonymousPacketToken: string;
+        apiKey: string;
+        hmacSecret: string;
+        encryptRequests: boolean;
+        activeTxId: string | null;
+        keepSession: boolean;
+        refreshBuffer: number;
+        onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+        onSessionExpired?: (error: Error) => void;
+        _sessionRefreshToken: string | null;
+        _refreshTimer: ReturnType<typeof setTimeout> | null;
+        configure(options: Partial<import("..").EntityServerClientOptions>): void;
+        setToken(token: string): void;
+        setAnonymousPacketToken(token: string): void;
+        setApiKey(apiKey: string): void;
+        setHmacSecret(secret: string): void;
+        setEncryptRequests(value: boolean): void;
+        _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+            access_token: string;
+            expires_in: number;
+        }>): void;
+        _clearRefreshTimer(): void;
+        stopKeepSession(): void;
+        readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+        get _reqOpts(): import("../client/request").RequestOptions;
+        requestJson<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+        requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+        _request<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+        _requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+    };
+} & TBase;

package/dist/mixins/utils.d.ts

@@ -0,0 +1,88 @@
+import type { QRCodeOptions, BarcodeOptions, Pdf2PngOptions } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+export declare function UtilsMixin<TBase extends GConstructor<EntityServerClientBase>>(Base: TBase): {
+    new (...args: any[]): {
+        /**
+         * 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>;
+        /**
+         * 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;
+        }>;
+        /** QR 코드를 ASCII 아트 텍스트로 반환합니다. */
+        qrcodeText(content: string, opts?: QRCodeOptions): Promise<{
+            ok: boolean;
+            text: string;
+        }>;
+        /**
+         * 바코드 PNG를 생성합니다. `ArrayBuffer`를 반환합니다.
+         *
+         * ```ts
+         * const buf = await client.barcode("1234567890128", { type: "ean13" });
+         * ```
+         */
+        barcode(content: string, opts?: BarcodeOptions): Promise<ArrayBuffer>;
+        /**
+         * 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>;
+        baseUrl: string;
+        token: string;
+        anonymousPacketToken: string;
+        apiKey: string;
+        hmacSecret: string;
+        encryptRequests: boolean;
+        activeTxId: string | null;
+        keepSession: boolean;
+        refreshBuffer: number;
+        onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+        onSessionExpired?: (error: Error) => void;
+        _sessionRefreshToken: string | null;
+        _refreshTimer: ReturnType<typeof setTimeout> | null;
+        configure(options: Partial<import("..").EntityServerClientOptions>): void;
+        setToken(token: string): void;
+        setAnonymousPacketToken(token: string): void;
+        setApiKey(apiKey: string): void;
+        setHmacSecret(secret: string): void;
+        setEncryptRequests(value: boolean): void;
+        _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+            access_token: string;
+            expires_in: number;
+        }>): void;
+        _clearRefreshTimer(): void;
+        stopKeepSession(): void;
+        readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+        get _reqOpts(): import("../client/request").RequestOptions;
+        requestJson<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+        requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+        _request<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+        _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+        _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+        _requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+    };
+} & TBase;

package/dist/packet.d.ts

@@ -0,0 +1,11 @@
+export declare const PACKET_KEY_SIZE = 32;
+export declare const PACKET_MAGIC_MIN = 2;
+export declare const PACKET_MAGIC_RANGE = 14;
+export declare const PACKET_NONCE_SIZE = 24;
+export declare const PACKET_TAG_SIZE = 16;
+export declare const PACKET_HKDF_SALT = "entity-server:hkdf:v1";
+export declare const PACKET_INFO_LABEL = "entity-server:packet-encryption";
+export declare function derivePacketKey(source: string, infoLabel?: string): Uint8Array;
+export declare function packetMagicLenFromKey(key: ArrayBuffer | Uint8Array, magicMin?: number, magicRange?: number): number;
+export declare function encryptPacket(plaintext: ArrayBuffer | Uint8Array, key: ArrayBuffer | Uint8Array, magicMin?: number, magicRange?: number): Uint8Array;
+export declare function decryptPacket(buffer: ArrayBuffer | Uint8Array, key: ArrayBuffer | Uint8Array, magicMin?: number, magicRange?: number): Uint8Array;

package/dist/packet.js

@@ -0,0 +1,2 @@
+import{xchacha20poly1305 as h}from"@noble/ciphers/chacha";import{sha256 as d}from"@noble/hashes/sha2";import{hkdf as m}from"@noble/hashes/hkdf";var f=32,u=2,E=14,o=24,T=16,k="entity-server:hkdf:v1",B="entity-server:packet-encryption";function s(r){return r instanceof Uint8Array?r:new Uint8Array(r)}function P(r,e=B){return m(d,new TextEncoder().encode(r),new TextEncoder().encode(k),new TextEncoder().encode(e),f)}function U(r,e=u,c=E){let n=s(r);return n.length<f?e:e+n[f-1]%c}function g(r,e,c=u,n=E){let i=s(r),y=s(e),t=U(y,c,n),p=crypto.getRandomValues(new Uint8Array(t)),a=crypto.getRandomValues(new Uint8Array(o)),x=h(y,a).encrypt(i),A=new Uint8Array(t+o+x.length);return A.set(p,0),A.set(a,t),A.set(x,t+o),A}function w(r,e,c=u,n=E){let i=s(r),y=s(e),t=U(y,c,n);if(i.length<t+o+T)throw new Error("Encrypted packet too short");let p=i.slice(t,t+o),a=i.slice(t+o);return h(y,p).decrypt(a)}export{k as PACKET_HKDF_SALT,B as PACKET_INFO_LABEL,f as PACKET_KEY_SIZE,u as PACKET_MAGIC_MIN,E as PACKET_MAGIC_RANGE,o as PACKET_NONCE_SIZE,T as PACKET_TAG_SIZE,w as decryptPacket,P as derivePacketKey,g as encryptPacket,U as packetMagicLenFromKey};
+//# sourceMappingURL=packet.js.map

package/dist/packet.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/packet.ts"],
+  "sourcesContent": ["// @ts-ignore\nimport { xchacha20poly1305 } from \"@noble/ciphers/chacha\";\n// @ts-ignore\nimport { sha256 } from \"@noble/hashes/sha2\";\n// @ts-ignore\nimport { hkdf } from \"@noble/hashes/hkdf\";\n\nexport const PACKET_KEY_SIZE = 32;\nexport const PACKET_MAGIC_MIN = 2;\nexport const PACKET_MAGIC_RANGE = 14;\nexport const PACKET_NONCE_SIZE = 24;\nexport const PACKET_TAG_SIZE = 16;\nexport const PACKET_HKDF_SALT = \"entity-server:hkdf:v1\";\nexport const PACKET_INFO_LABEL = \"entity-server:packet-encryption\";\n\nfunction toUint8Array(data: ArrayBuffer | Uint8Array): Uint8Array {\n    return data instanceof Uint8Array ? data : new Uint8Array(data);\n}\n\nexport function derivePacketKey(\n    source: string,\n    infoLabel = PACKET_INFO_LABEL,\n): Uint8Array {\n    return hkdf(\n        sha256,\n        new TextEncoder().encode(source),\n        new TextEncoder().encode(PACKET_HKDF_SALT),\n        new TextEncoder().encode(infoLabel),\n        PACKET_KEY_SIZE,\n    );\n}\n\nexport function packetMagicLenFromKey(\n    key: ArrayBuffer | Uint8Array,\n    magicMin = PACKET_MAGIC_MIN,\n    magicRange = PACKET_MAGIC_RANGE,\n): number {\n    const keyBytes = toUint8Array(key);\n    if (keyBytes.length < PACKET_KEY_SIZE) return magicMin;\n    return magicMin + (keyBytes[PACKET_KEY_SIZE - 1]! % magicRange);\n}\n\nexport function encryptPacket(\n    plaintext: ArrayBuffer | Uint8Array,\n    key: ArrayBuffer | Uint8Array,\n    magicMin = PACKET_MAGIC_MIN,\n    magicRange = PACKET_MAGIC_RANGE,\n): Uint8Array {\n    const plaintextBytes = toUint8Array(plaintext);\n    const keyBytes = toUint8Array(key);\n    const magicLen = packetMagicLenFromKey(keyBytes, magicMin, magicRange);\n    const magic = crypto.getRandomValues(new Uint8Array(magicLen));\n    const nonce = crypto.getRandomValues(new Uint8Array(PACKET_NONCE_SIZE));\n    const cipher = xchacha20poly1305(keyBytes, nonce);\n    const ciphertext = cipher.encrypt(plaintextBytes);\n    const result = new Uint8Array(\n        magicLen + PACKET_NONCE_SIZE + ciphertext.length,\n    );\n\n    result.set(magic, 0);\n    result.set(nonce, magicLen);\n    result.set(ciphertext, magicLen + PACKET_NONCE_SIZE);\n    return result;\n}\n\nexport function decryptPacket(\n    buffer: ArrayBuffer | Uint8Array,\n    key: ArrayBuffer | Uint8Array,\n    magicMin = PACKET_MAGIC_MIN,\n    magicRange = PACKET_MAGIC_RANGE,\n): Uint8Array {\n    const data = toUint8Array(buffer);\n    const keyBytes = toUint8Array(key);\n    const magicLen = packetMagicLenFromKey(keyBytes, magicMin, magicRange);\n\n    if (data.length < magicLen + PACKET_NONCE_SIZE + PACKET_TAG_SIZE) {\n        throw new Error(\"Encrypted packet too short\");\n    }\n\n    const nonce = data.slice(magicLen, magicLen + PACKET_NONCE_SIZE);\n    const ciphertext = data.slice(magicLen + PACKET_NONCE_SIZE);\n    const cipher = xchacha20poly1305(keyBytes, nonce);\n    return cipher.decrypt(ciphertext);\n}\n"],
+  "mappings": "AACA,OAAS,qBAAAA,MAAyB,wBAElC,OAAS,UAAAC,MAAc,qBAEvB,OAAS,QAAAC,MAAY,qBAEd,IAAMC,EAAkB,GAClBC,EAAmB,EACnBC,EAAqB,GACrBC,EAAoB,GACpBC,EAAkB,GAClBC,EAAmB,wBACnBC,EAAoB,kCAEjC,SAASC,EAAaC,EAA4C,CAC9D,OAAOA,aAAgB,WAAaA,EAAO,IAAI,WAAWA,CAAI,CAClE,CAEO,SAASC,EACZC,EACAC,EAAYL,EACF,CACV,OAAOP,EACHD,EACA,IAAI,YAAY,EAAE,OAAOY,CAAM,EAC/B,IAAI,YAAY,EAAE,OAAOL,CAAgB,EACzC,IAAI,YAAY,EAAE,OAAOM,CAAS,EAClCX,CACJ,CACJ,CAEO,SAASY,EACZC,EACAC,EAAWb,EACXc,EAAab,EACP,CACN,IAAMc,EAAWT,EAAaM,CAAG,EACjC,OAAIG,EAAS,OAAShB,EAAwBc,EACvCA,EAAYE,EAAShB,EAAkB,CAAC,EAAKe,CACxD,CAEO,SAASE,EACZC,EACAL,EACAC,EAAWb,EACXc,EAAab,EACH,CACV,IAAMiB,EAAiBZ,EAAaW,CAAS,EACvCF,EAAWT,EAAaM,CAAG,EAC3BO,EAAWR,EAAsBI,EAAUF,EAAUC,CAAU,EAC/DM,EAAQ,OAAO,gBAAgB,IAAI,WAAWD,CAAQ,CAAC,EACvDE,EAAQ,OAAO,gBAAgB,IAAI,WAAWnB,CAAiB,CAAC,EAEhEoB,EADS1B,EAAkBmB,EAAUM,CAAK,EACtB,QAAQH,CAAc,EAC1CK,EAAS,IAAI,WACfJ,EAAWjB,EAAoBoB,EAAW,MAC9C,EAEA,OAAAC,EAAO,IAAIH,EAAO,CAAC,EACnBG,EAAO,IAAIF,EAAOF,CAAQ,EAC1BI,EAAO,IAAID,EAAYH,EAAWjB,CAAiB,EAC5CqB,CACX,CAEO,SAASC,EACZC,EACAb,EACAC,EAAWb,EACXc,EAAab,EACH,CACV,IAAMM,EAAOD,EAAamB,CAAM,EAC1BV,EAAWT,EAAaM,CAAG,EAC3BO,EAAWR,EAAsBI,EAAUF,EAAUC,CAAU,EAErE,GAAIP,EAAK,OAASY,EAAWjB,EAAoBC,EAC7C,MAAM,IAAI,MAAM,4BAA4B,EAGhD,IAAMkB,EAAQd,EAAK,MAAMY,EAAUA,EAAWjB,CAAiB,EACzDoB,EAAaf,EAAK,MAAMY,EAAWjB,CAAiB,EAE1D,OADeN,EAAkBmB,EAAUM,CAAK,EAClC,QAAQC,CAAU,CACpC",
+  "names": ["xchacha20poly1305", "sha256", "hkdf", "PACKET_KEY_SIZE", "PACKET_MAGIC_MIN", "PACKET_MAGIC_RANGE", "PACKET_NONCE_SIZE", "PACKET_TAG_SIZE", "PACKET_HKDF_SALT", "PACKET_INFO_LABEL", "toUint8Array", "data", "derivePacketKey", "source", "infoLabel", "packetMagicLenFromKey", "key", "magicMin", "magicRange", "keyBytes", "encryptPacket", "plaintext", "plaintextBytes", "magicLen", "magic", "nonce", "ciphertext", "result", "decryptPacket", "buffer"]
+}