entity-server-client 0.3.1 → 1.0.0

package/dist/EntityServerClient.d.ts

@@ -0,0 +1,432 @@
+/**
+ * @file EntityServerClient.ts
+ * Mixin 패턴으로 구성된 EntityServerClient.
+ *
+ * 절(section)별 구현:
+ *   src/client/base.ts      — 상태·생성자·공통 헬퍼
+ *   src/mixins/auth.ts      — 인증 (로그인/로그아웃/me/트랜잭션 등)
+ *   src/mixins/entity.ts    — 트랜잭션 & 엔티티 CRUD
+ *   src/mixins/push.ts      — 푸시 디바이스 관리
+ *   src/mixins/smtp.ts      — SMTP 메일 발송
+ *   src/mixins/file.ts      — 파일 스토리지
+ *   src/mixins/utils.ts     — QR코드/바코드/PDF변환
+ */
+import { EntityServerClientBase } from "./client/base";
+declare const EntityServerClient_base: {
+    new (...args: any[]): {
+        qrcode(content: string, opts?: import("./types").QRCodeOptions): Promise<ArrayBuffer>;
+        qrcodeBase64(content: string, opts?: import("./types").QRCodeOptions): Promise<{
+            ok: boolean;
+            data: string;
+            data_uri: string;
+        }>;
+        qrcodeText(content: string, opts?: import("./types").QRCodeOptions): Promise<{
+            ok: boolean;
+            text: string;
+        }>;
+        barcode(content: string, opts?: import("./types").BarcodeOptions): Promise<ArrayBuffer>;
+        pdf2png(pdfData: ArrayBuffer | Uint8Array<ArrayBuffer>, opts?: import("./types").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("./types").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>;
+    };
+} & {
+    new (...args: any[]): {
+        fileUpload(entity: string, file: File | Blob, opts?: import("./types").FileUploadOptions): Promise<{
+            ok: boolean;
+            uuid: string;
+            data: import("./types").FileMeta;
+        }>;
+        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: import("./types").FileMeta[];
+                total: number;
+            };
+        }>;
+        fileMeta(entity: string, uuid: string): Promise<{
+            ok: boolean;
+            data: import("./types").FileMeta;
+        }>;
+        fileToken(uuid: string): Promise<{
+            ok: boolean;
+            token: string;
+        }>;
+        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("./types").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>;
+    };
+} & {
+    new (...args: any[]): {
+        smtpSend(req: import("./types").SmtpSendRequest): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        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("./types").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>;
+    };
+} & {
+    new (...args: any[]): {
+        push(pushEntity: string, payload: Record<string, unknown>, opts?: {
+            transactionId?: string;
+        }): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        pushLogList<T = unknown>(params?: import("./types").EntityListParams): Promise<{
+            ok: boolean;
+            data: import("./types").EntityListResult<T>;
+        }>;
+        registerPushDevice(accountSeq: number, deviceId: string, pushToken: string, opts?: import("./types").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("./types").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?: import("./types").EntityListParams): Promise<{
+            ok: boolean;
+            data: import("./types").EntityListResult<T>;
+        }>;
+    };
+} & {
+    new (...args: any[]): {
+        transStart(): Promise<string>;
+        transRollback(transactionId?: string): Promise<{
+            ok: boolean;
+        }>;
+        transCommit(transactionId?: string): Promise<{
+            ok: boolean;
+            results: {
+                entity: string;
+                action: string;
+                seq: number;
+            }[];
+        }>;
+        get<T = unknown>(entity: string, seq: number, opts?: {
+            skipHooks?: boolean;
+        }): Promise<{
+            ok: boolean;
+            data: T;
+        }>;
+        find<T = unknown>(entity: string, conditions?: Record<string, unknown>, opts?: {
+            skipHooks?: boolean;
+        }): Promise<{
+            ok: boolean;
+            data: T;
+        }>;
+        list<T = unknown>(entity: string, params?: import("./types").EntityListParams): Promise<{
+            ok: boolean;
+            data: import("./types").EntityListResult<T>;
+        }>;
+        count(entity: string, conditions?: Record<string, unknown>): Promise<{
+            ok: boolean;
+            count: number;
+        }>;
+        query<T = unknown>(entity: string, req: import("./types").EntityQueryRequest): Promise<{
+            ok: boolean;
+            data: {
+                items: T[];
+                count: number;
+            };
+        }>;
+        submit(entity: string, data: Record<string, unknown>, opts?: {
+            transactionId?: string;
+            skipHooks?: boolean;
+        }): Promise<{
+            ok: boolean;
+            seq: number;
+        }>;
+        delete(entity: string, seq: number, opts?: {
+            transactionId?: string;
+            hard?: boolean;
+            skipHooks?: boolean;
+        }): Promise<{
+            ok: boolean;
+            deleted: number;
+        }>;
+        history<T = unknown>(entity: string, seq: number, params?: Pick<import("./types").EntityListParams, "page" | "limit">): Promise<{
+            ok: boolean;
+            data: import("./types").EntityListResult<import("./types").EntityHistoryRecord<T>>;
+        }>;
+        rollback(entity: string, historySeq: number): Promise<{
+            ok: boolean;
+        }>;
+        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("./types").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>;
+    };
+} & {
+    new (...args: any[]): {
+        checkHealth(): Promise<{
+            ok: boolean;
+            packet_encryption?: boolean;
+            packet_mode?: string;
+            packet_token?: string;
+        }>;
+        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;
+        }>;
+        refreshToken(refreshToken: string): Promise<{
+            access_token: string;
+            expires_in: number;
+        }>;
+        logout(refreshToken: string): Promise<{
+            ok: boolean;
+        }>;
+        me<T = Record<string, unknown>>(): Promise<{
+            ok: boolean;
+            data: T;
+        }>;
+        withdraw(passwd?: string): Promise<{
+            ok: boolean;
+        }>;
+        reactivate(params: {
+            email: string;
+            passwd?: string;
+            provider?: string;
+            code?: string;
+        }): Promise<{
+            access_token: string;
+            refresh_token: string;
+            expires_in: 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("./types").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>;
+    };
+} & typeof EntityServerClientBase;
+export declare class EntityServerClient extends EntityServerClient_base {
+}
+export {};

package/dist/client/base.d.ts

@@ -0,0 +1,84 @@
+import type { EntityServerClientOptions } from "../types";
+import { type RequestOptions } from "./request";
+export type GConstructor<T = object> = new (...args: any[]) => T;
+export declare class EntityServerClientBase {
+    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;
+    /**
+     * EntityServerClient 인스턴스를 생성합니다.
+     *
+     * 기본값:
+     * - `baseUrl`: `VITE_ENTITY_SERVER_URL` 또는 상대 경로(`""`)
+     */
+    constructor(options?: EntityServerClientOptions);
+    /** baseUrl, token, encryptRequests 값을 런타임에 갱신합니다. */
+    configure(options: Partial<EntityServerClientOptions>): void;
+    /** 인증 요청에 사용할 JWT Access Token을 설정합니다. */
+    setToken(token: string): void;
+    /** 익명 패킷 암호화용 토큰을 설정합니다. */
+    setAnonymousPacketToken(token: string): void;
+    /** HMAC 인증용 API Key를 설정합니다. */
+    setApiKey(apiKey: string): void;
+    /** HMAC 인증용 시크릿을 설정합니다. */
+    setHmacSecret(secret: string): void;
+    /** 암호화 요청 활성화 여부를 설정합니다. */
+    setEncryptRequests(value: boolean): void;
+    /** @internal 자동 토큰 갱신 타이머를 시작합니다. */
+    _scheduleKeepSession(refreshToken: string, expiresIn: number, refreshFn: (rt: string) => Promise<{
+        access_token: string;
+        expires_in: number;
+    }>): void;
+    /** @internal 자동 갱신 타이머를 정리합니다. */
+    _clearRefreshTimer(): void;
+    /**
+     * 세션 유지 타이머를 중지합니다.
+     * `logout()` 호출 시 자동으로 중지되며, 직접 호출이 필요한 경우는 드뭅니다.
+     */
+    stopKeepSession(): void;
+    /**
+     * 요청 바디를 파싱합니다.
+     * `application/octet-stream`이면 XChaCha20-Poly1305 복호화, 그 외는 JSON 파싱합니다.
+     *
+     * @param requireEncrypted `true`이면 암호화된 요청만 허용합니다.
+     */
+    readRequestBody<T = Record<string, unknown>>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType?: string, requireEncrypted?: boolean): T;
+    get _reqOpts(): RequestOptions;
+    /**
+     * 임의 경로에 JSON 요청을 보냅니다. 응답이 JSON이면 파싱, octet-stream이면 자동 복호화합니다.
+     * `ok` 필드를 강제하지 않아 go서버/앱서버 신규 라우트 등 자유 응답 포맷에 사용합니다.
+     * `encryptRequests: true`이면 요청 바디도 자동 암호화됩니다.
+     */
+    requestJson<T>(method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>): Promise<T>;
+    /**
+     * 임의 경로에 요청을 보내고 바이너리(ArrayBuffer)를 반환합니다.
+     * 이미지, PDF, 압축 파일 등 바이너리 응답이 오는 엔드포인트에 사용합니다.
+     */
+    requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+    /**
+     * multipart/form-data 요청을 보냅니다. 파일 업로드 등에 사용합니다.
+     * 응답은 JSON으로 파싱하여 반환합니다.
+     */
+    requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+    /**
+     * multipart/form-data 요청을 보내고 바이너리(ArrayBuffer)를 반환합니다.
+     */
+    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>;
+    /** PNG/바이너리 응답을 ArrayBuffer로 반환합니다. (QR, 바코드 등) */
+    _requestBinary(method: string, path: string, body?: unknown, withAuth?: boolean): Promise<ArrayBuffer>;
+    /** multipart/form-data 요청을 보냅니다. (파일 업로드 등) */
+    _requestForm<T>(method: string, path: string, form: FormData, withAuth?: boolean): Promise<T>;
+    /** multipart/form-data 요청을 보내고 바이너리(ArrayBuffer)를 반환합니다. */
+    _requestFormBinary(method: string, path: string, form: FormData, withAuth?: boolean): Promise<ArrayBuffer>;
+}

package/dist/client/hmac.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HMAC-SHA256 서명 헤더를 생성합니다.
+ *
+ * 서명 대상: `METHOD|PATH|TIMESTAMP|NONCE|BODY`
+ *
+ * @returns `X-API-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature` 헤더 객체
+ */
+export declare function buildHmacHeaders(method: string, path: string, bodyBytes: Uint8Array, apiKey: string, hmacSecret: string): Record<string, string>;

package/dist/client/packet.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 패킷 암호화 키를 유도합니다.
+ * - HMAC 모드 (`hmacSecret` 유효 시): HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+ * - JWT  모드: HKDF-SHA256(jwt_token, "entity-server:packet-encryption")
+ */
+export declare function derivePacketKey(hmacSecret: string, token: string): Uint8Array;
+/**
+ * 평문 바이트를 XChaCha20-Poly1305로 암호화합니다.
+ * 포맷: [random_magic:K][random_nonce:24][ciphertext+tag]
+ * K = 2 + key[31] % 14 (패킷 키에서 자동 파생)
+ */
+export declare function encryptPacket(plaintext: Uint8Array, key: Uint8Array): Uint8Array;
+/**
+ * XChaCha20-Poly1305 패킷을 복호화해 JSON 객체로 변환합니다.
+ * 포맷: [magic:K][nonce:24][ciphertext+tag]
+ * K = 2 + key[31] % 14 (패킷 키에서 자동 파생)
+ */
+export declare function decryptPacket<T>(buffer: ArrayBuffer, key: Uint8Array): T;
+/**
+ * 요청 바디를 파싱합니다. `application/octet-stream`이면 복호화, 그 외는 JSON 파싱합니다.
+ *
+ * @param requireEncrypted `true`이면 암호화된 요청만 허용합니다.
+ */
+export declare function parseRequestBody<T>(body: ArrayBuffer | Uint8Array | string | T | null | undefined, contentType: string, requireEncrypted: boolean, key: Uint8Array): T;

package/dist/client/request.d.ts

@@ -0,0 +1,16 @@
+export interface RequestOptions {
+    baseUrl: string;
+    token: string;
+    anonymousPacketToken: string;
+    apiKey: string;
+    hmacSecret: string;
+    encryptRequests: boolean;
+}
+/**
+ * Entity Server에 HTTP 요청을 보냅니다.
+ *
+ * - `encryptRequests` 활성화 시 인증된 POST 바디를 자동 암호화합니다.
+ * - 응답이 `application/octet-stream`이면 자동 복호화합니다.
+ * - JSON 응답의 `ok`가 false이면 에러를 던집니다.
+ */
+export declare function entityRequest<T>(opts: RequestOptions, method: string, path: string, body?: unknown, withAuth?: boolean, extraHeaders?: Record<string, string>, requireOkShape?: boolean): Promise<T>;

package/dist/client/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 환경변수를 읽습니다.
+ * - 브라우저/Vite: `import.meta.env`
+ * - Node.js: `process.env`
+ */
+export declare function readEnv(name: string): string | undefined;
+/** 쿼리 파라미터 객체를 URL 쿼리 문자열로 변환합니다. `orderBy` 키는 `order_by`로 변환됩니다. */
+export declare function buildQuery(params: Record<string, unknown>): string;

package/dist/hooks/useEntityServer.d.ts

@@ -0,0 +1,63 @@
+import { EntityServerClient, type EntityQueryRequest, type EntityServerClientOptions } from "../index";
+export interface UseEntityServerOptions extends EntityServerClientOptions {
+    singleton?: boolean;
+    tokenResolver?: () => string | undefined | null;
+    /**
+     * 페이지 새로고침 후 로그인 상태를 복원할 때 사용합니다.
+     * 이 값이 있으면 마운트 시 `client.refreshToken()`을 호출해 새 access_token을 발급받습니다.
+     * `keepSession: true`와 함께 사용하면 세션 유지 타이머도 재시작됩니다.
+     * 갱신 성공 시 `onTokenRefreshed` 콜백이 호출됩니다.
+     */
+    resumeSession?: string;
+}
+export interface UseEntityServerResult {
+    /** EntityServerClient 인스턴스 (read 전용 메서드 직접 호출 시 사용) */
+    client: EntityServerClient;
+    /** submit 또는 delete 진행 중 여부 */
+    isPending: boolean;
+    /** 마지막 mutation 에러 (없으면 null) */
+    error: Error | null;
+    /** 에러·결과 상태 초기화 */
+    reset: () => void;
+    /** entity 데이터 생성/수정 (seq 없으면 INSERT, 있으면 UPDATE) */
+    submit: (entity: string, data: Record<string, unknown>, opts?: {
+        transactionId?: string;
+        skipHooks?: boolean;
+    }) => Promise<{
+        ok: boolean;
+        seq: number;
+    }>;
+    /** entity 데이터 삭제 */
+    del: (entity: string, seq: number, opts?: {
+        transactionId?: string;
+        hard?: boolean;
+        skipHooks?: boolean;
+    }) => Promise<{
+        ok: boolean;
+        deleted: number;
+    }>;
+    /** 커스텀 SQL 조회 */
+    query: <T = unknown>(entity: string, req: EntityQueryRequest) => Promise<{
+        ok: boolean;
+        data: {
+            items: T[];
+            count: number;
+        };
+    }>;
+}
+/**
+ * React 환경에서 EntityServerClient 인스턴스와 mutation 상태를 반환합니다.
+ *
+ * - `singleton=true`(기본): 패키지 전역 `entityServer` 인스턴스를 사용합니다.
+ * - `singleton=false`: 컴포넌트 스코프의 새 인스턴스를 생성합니다.
+ *
+ * @example
+ * ```tsx
+ * const { submit, del, isPending, error, reset } = useEntityServer();
+ *
+ * const handleSave = async () => {
+ *     await submit("account", { name: "홍길동" });
+ * };
+ * ```
+ */
+export declare function useEntityServer(options?: UseEntityServerOptions): UseEntityServerResult;

package/{src/index.ts → dist/index.d.ts}

@@ -1,6 +1,4 @@
 export * from "./types";
 export * from "./EntityServerClient";
-
 import { EntityServerClient } from "./EntityServerClient";
-
-export const entityServer = new EntityServerClient();
+export declare const entityServer: EntityServerClient;