create-entity-server 0.0.9 → 0.0.15

package/template/samples/php/ci4/Libraries/EntityServer.php

@@ -2,6 +2,8 @@
 
 namespace App\Libraries;
 
+use Config\EntityServer as EntityServerConfig;
+
 /**
  * Entity Server 클라이언트 라이브러리 (CodeIgniter 4)
  *
@@ -9,7 +11,7 @@ namespace App\Libraries;
  *
  * 설치: app/Libraries/EntityServer.php 에 배치
  *
- * 설정: app/Config/EntityServer.php 또는 .env 에서
+ * 설정: app/Config/EntityServer.php 우선 (필요시 .env fallback)
  *   ENTITY_SERVER_URL=http://localhost:47200
  *   ENTITY_SERVER_API_KEY=your-api-key
  *   ENTITY_SERVER_HMAC_SECRET=your-hmac-secret
@@ -28,20 +30,32 @@ class EntityServer
     private string  $hmacSecret;
     private int     $timeout;
     private int     $magicLen;
+    private bool    $requireEncryptedRequest;
     private ?string $activeTxId = null;
 
     public function __construct(
-        string $baseUrl    = '',
-        string $apiKey     = '',
-        string $hmacSecret = '',
-        int    $timeout    = 10,
-        int    $magicLen   = 4
+        ?string $baseUrl    = null,
+        ?string $apiKey     = null,
+        ?string $hmacSecret = null,
+        ?int    $timeout    = null,
+        ?int    $magicLen   = null,
+        ?bool   $requireEncryptedRequest = null
     ) {
-        $this->baseUrl    = rtrim($baseUrl    ?: env('ENTITY_SERVER_URL',           'http://localhost:47200'), '/');
-        $this->apiKey     = $apiKey           ?: env('ENTITY_SERVER_API_KEY',      '');
-        $this->hmacSecret = $hmacSecret       ?: env('ENTITY_SERVER_HMAC_SECRET',  '');
-        $this->timeout    = $timeout;
-        $this->magicLen   = (int) ($magicLen  ?: env('ENTITY_PACKET_MAGIC_LEN',    4));
+        $config = class_exists(EntityServerConfig::class) ? new EntityServerConfig() : null;
+
+        $configBaseUrl = $config?->baseUrl ?? env('ENTITY_SERVER_URL', 'http://localhost:47200');
+        $configApiKey = $config?->apiKey ?? env('ENTITY_SERVER_API_KEY', '');
+        $configHmacSecret = $config?->hmacSecret ?? env('ENTITY_SERVER_HMAC_SECRET', '');
+        $configTimeout = $config?->timeout ?? (int) env('ENTITY_SERVER_TIMEOUT', 10);
+        $configMagicLen = $config?->magicLen ?? (int) env('ENTITY_PACKET_MAGIC_LEN', 4);
+        $configRequireEncrypted = $config?->requireEncryptedRequest ?? true;
+
+        $this->baseUrl = rtrim($baseUrl ?? (string) $configBaseUrl, '/');
+        $this->apiKey = (string) ($apiKey ?? $configApiKey);
+        $this->hmacSecret = (string) ($hmacSecret ?? $configHmacSecret);
+        $this->timeout = (int) ($timeout ?? $configTimeout);
+        $this->magicLen = (int) ($magicLen ?? $configMagicLen);
+        $this->requireEncryptedRequest = (bool) ($requireEncryptedRequest ?? $configRequireEncrypted);
     }
 
     // ─── CRUD ────────────────────────────────────────────────────────────────
@@ -155,6 +169,131 @@ class EntityServer
         return $this->request('POST', "/v1/entity/{$entity}/rollback/{$historySeq}");
     }
 
+    /**
+     * 푸시 발송 트리거 엔티티에 submit합니다.
+     */
+    public function push(string $pushEntity, array $payload, ?string $transactionId = null): array
+    {
+        return $this->submit($pushEntity, $payload, $transactionId);
+    }
+
+    /**
+     * push_log 목록 조회 헬퍼
+     */
+    public function pushLogList(array $params = []): array
+    {
+        return $this->list('push_log', $params);
+    }
+
+    /**
+     * 디바이스 등록/갱신 헬퍼 (push_token 단일 필드)
+     *
+     * - 기본 대상 엔티티: account_device
+     * - 신규 등록: seq 미전달
+     * - 기존 레코드 갱신: options['seq'] 전달
+     *
+     * @param int         $accountSeq    계정 seq
+     * @param string      $deviceId      디바이스 고유 ID (account_device.id)
+     * @param string      $pushToken     푸시 디바이스 토큰
+     * @param array       $options       추가 필드 (예: platform, device_type, browser, push_enabled, seq)
+     * @param string|null $transactionId transStart()로 얻은 트랜잭션 ID
+     */
+    public function registerPushDevice(
+        int $accountSeq,
+        string $deviceId,
+        string $pushToken,
+        array $options = [],
+        ?string $transactionId = null
+    ): array {
+        $payload = array_merge([
+            'id' => $deviceId,
+            'account_seq' => $accountSeq,
+            'push_token' => $pushToken,
+            'push_enabled' => true,
+        ], $options);
+
+        return $this->submit('account_device', $payload, $transactionId);
+    }
+
+    /**
+     * account_device.seq 기준으로 push_token 갱신
+     */
+    public function updatePushDeviceToken(
+        int $deviceSeq,
+        string $pushToken,
+        bool $pushEnabled = true,
+        ?string $transactionId = null
+    ): array {
+        return $this->submit('account_device', [
+            'seq' => $deviceSeq,
+            'push_token' => $pushToken,
+            'push_enabled' => $pushEnabled,
+        ], $transactionId);
+    }
+
+    /**
+     * account_device.seq 기준으로 푸시 수신 비활성화
+     */
+    public function disablePushDevice(
+        int $deviceSeq,
+        ?string $transactionId = null
+    ): array {
+        return $this->submit('account_device', [
+            'seq' => $deviceSeq,
+            'push_enabled' => false,
+        ], $transactionId);
+    }
+
+    /**
+     * CI4 IncomingRequest에서 암호화 패킷을 읽어 JSON 배열로 복호화합니다.
+     *
+     * @param object $request CodeIgniter\HTTP\IncomingRequest
+     * @param bool   $requireEncrypted true면 평문 JSON 요청을 거부합니다.
+     */
+    public function readRequestBody(object $request, ?bool $requireEncrypted = null): array
+    {
+        $requireEncrypted = $requireEncrypted ?? $this->requireEncryptedRequest;
+
+        $contentType = '';
+        if (method_exists($request, 'getHeaderLine')) {
+            $contentType = strtolower((string) $request->getHeaderLine('Content-Type'));
+        }
+
+        $rawBody = '';
+        if (method_exists($request, 'getBody')) {
+            $rawBody = (string) $request->getBody();
+        }
+
+        $isEncryptedPacket = str_contains($contentType, 'application/octet-stream');
+
+        if ($requireEncrypted && !$isEncryptedPacket) {
+            throw new \RuntimeException('Encrypted request required: Content-Type must be application/octet-stream');
+        }
+
+        if ($isEncryptedPacket) {
+            if ($rawBody === '') {
+                throw new \RuntimeException('Encrypted request body is empty');
+            }
+
+            $jsonStr = $this->decryptPacket($rawBody);
+            $decoded = json_decode($jsonStr, true);
+            if (!is_array($decoded)) {
+                throw new \RuntimeException('Invalid encrypted JSON payload');
+            }
+            return $decoded;
+        }
+
+        // 선택적으로 평문 허용할 때만 fallback
+        if ($rawBody === '') {
+            return [];
+        }
+        $decoded = json_decode($rawBody, true);
+        if (!is_array($decoded)) {
+            throw new \RuntimeException('Invalid JSON payload');
+        }
+        return $decoded;
+    }
+
     // ─── 내부 ─────────────────────────────────────────────────────────────────
 
     private function request(string $method, string $path, array $body = [], array $extraHeaders = []): array

package/template/samples/php/laravel/Services/EntityServerService.php

@@ -4,6 +4,7 @@ namespace App\Services;
 
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Str;
+use Illuminate\Http\Request;
 
 /**
  * Entity Server 클라이언트 서비스 (Laravel)
@@ -40,6 +41,7 @@ class EntityServerService
     private string  $apiKey;
     private string  $hmacSecret;
     private int     $magicLen;
+    private bool    $requireEncryptedRequest;
     private ?string $activeTxId = null;
 
     public function __construct()
@@ -48,6 +50,7 @@ class EntityServerService
         $this->apiKey     = config('services.entity_server.api_key',     env('ENTITY_SERVER_API_KEY',     ''));
         $this->hmacSecret = config('services.entity_server.hmac_secret', env('ENTITY_SERVER_HMAC_SECRET', ''));
         $this->magicLen   = (int) config('services.entity_server.packet_magic_len', env('ENTITY_PACKET_MAGIC_LEN', 4));
+        $this->requireEncryptedRequest = (bool) config('services.entity_server.require_encrypted_request', env('ENTITY_REQUIRE_ENCRYPTED_REQUEST', true));
     }
 
     // ─── CRUD ────────────────────────────────────────────────────────────────
@@ -138,6 +141,59 @@ class EntityServerService
         return $this->request('POST', "/v1/entity/{$entity}/rollback/{$historySeq}");
     }
 
+    /**
+     * 푸시 발송 트리거 엔티티에 submit합니다.
+     */
+    public function push(string $pushEntity, array $payload, ?string $transactionId = null): array
+    {
+        return $this->submit($pushEntity, $payload, $transactionId);
+    }
+
+    /**
+     * push_log 목록 조회 헬퍼
+     */
+    public function pushLogList(array $params = []): array
+    {
+        return $this->list('push_log', $params);
+    }
+
+    /**
+     * Laravel Request에서 암호화 패킷 또는 평문 JSON 본문을 읽어 배열로 반환합니다.
+     */
+    public function readRequestBody(Request $request, ?bool $requireEncrypted = null): array
+    {
+        $requireEncrypted = $requireEncrypted ?? $this->requireEncryptedRequest;
+
+        $contentType = strtolower((string) $request->header('Content-Type', ''));
+        $rawBody = (string) $request->getContent();
+        $isEncrypted = str_contains($contentType, 'application/octet-stream');
+
+        if ($requireEncrypted && !$isEncrypted) {
+            throw new \RuntimeException('Encrypted request required: Content-Type must be application/octet-stream');
+        }
+
+        if ($isEncrypted) {
+            if ($rawBody === '') {
+                throw new \RuntimeException('Encrypted request body is empty');
+            }
+            $jsonStr = $this->decryptPacket($rawBody);
+            $decoded = json_decode($jsonStr, true);
+            if (!is_array($decoded)) {
+                throw new \RuntimeException('Invalid encrypted JSON payload');
+            }
+            return $decoded;
+        }
+
+        if ($rawBody === '') {
+            return [];
+        }
+        $decoded = json_decode($rawBody, true);
+        if (!is_array($decoded)) {
+            throw new \RuntimeException('Invalid JSON payload');
+        }
+        return $decoded;
+    }
+
     // ─── 내부 ─────────────────────────────────────────────────────────────────
 
     private function request(string $method, string $path, array $body = [], array $extraHeaders = []): array

package/template/samples/python/entity_server.py

@@ -150,6 +150,112 @@ class EntityServerClient:
         """history seq 단위 롤백 (단건)"""
         return self._request("POST", f"/v1/entity/{entity}/rollback/{history_seq}")
 
+    def push(self, push_entity: str, payload: dict, *, transaction_id: str | None = None) -> dict:
+        """푸시 발송 트리거 엔티티에 submit합니다."""
+        return self.submit(push_entity, payload, transaction_id=transaction_id)
+
+    def push_log_list(self, page: int = 1, limit: int = 20, order_by: str | None = None) -> dict:
+        """push_log 목록 조회 헬퍼"""
+        return self.list("push_log", page=page, limit=limit, order_by=order_by)
+
+    def register_push_device(
+        self,
+        account_seq: int,
+        device_id: str,
+        push_token: str,
+        *,
+        platform: str | None = None,
+        device_type: str | None = None,
+        browser: str | None = None,
+        browser_version: str | None = None,
+        push_enabled: bool = True,
+        transaction_id: str | None = None,
+    ) -> dict:
+        """account_device 디바이스 등록/갱신 헬퍼 (push_token 단일 필드)"""
+        payload: dict[str, Any] = {
+            "id": device_id,
+            "account_seq": account_seq,
+            "push_token": push_token,
+            "push_enabled": push_enabled,
+        }
+        if platform:
+            payload["platform"] = platform
+        if device_type:
+            payload["device_type"] = device_type
+        if browser:
+            payload["browser"] = browser
+        if browser_version:
+            payload["browser_version"] = browser_version
+        return self.submit("account_device", payload, transaction_id=transaction_id)
+
+    def update_push_device_token(
+        self,
+        device_seq: int,
+        push_token: str,
+        *,
+        push_enabled: bool = True,
+        transaction_id: str | None = None,
+    ) -> dict:
+        """account_device.seq 기준 push_token 갱신 헬퍼"""
+        return self.submit(
+            "account_device",
+            {
+                "seq": device_seq,
+                "push_token": push_token,
+                "push_enabled": push_enabled,
+            },
+            transaction_id=transaction_id,
+        )
+
+    def disable_push_device(
+        self,
+        device_seq: int,
+        *,
+        transaction_id: str | None = None,
+    ) -> dict:
+        """account_device.seq 기준 푸시 수신 비활성화 헬퍼"""
+        return self.submit(
+            "account_device",
+            {
+                "seq": device_seq,
+                "push_enabled": False,
+            },
+            transaction_id=transaction_id,
+        )
+
+    def read_request_body(
+        self,
+        raw_body: bytes | str | None,
+        content_type: str = "application/json",
+        *,
+        require_encrypted: bool = False,
+    ) -> dict:
+        """요청 본문을 읽어 JSON으로 반환합니다.
+        - application/octet-stream: 암호 패킷 복호화
+        - 그 외: 평문 JSON 파싱
+        """
+        lowered = (content_type or "").lower()
+        is_encrypted = "application/octet-stream" in lowered
+
+        if require_encrypted and not is_encrypted:
+            raise RuntimeError(
+                "Encrypted request required: Content-Type must be application/octet-stream"
+            )
+
+        if is_encrypted:
+            if raw_body in (None, b"", ""):
+                raise RuntimeError("Encrypted request body is empty")
+
+            packet = raw_body if isinstance(raw_body, bytes) else raw_body.encode("utf-8")
+            return json.loads(self._decrypt_packet(packet))
+
+        if raw_body in (None, b"", ""):
+            return {}
+
+        if isinstance(raw_body, bytes):
+            return json.loads(raw_body.decode("utf-8"))
+        return json.loads(raw_body)
+
     # ─── 내부 ─────────────────────────────────────────────────────────────────
 
     def _request(

package/template/samples/react/src/api/entityServerClient.ts

@@ -39,6 +39,15 @@ export interface EntityQueryFilter {
     value: unknown;
 }
 
+export interface RegisterPushDeviceOptions {
+    platform?: string;
+    deviceType?: string;
+    browser?: string;
+    browserVersion?: string;
+    pushEnabled?: boolean;
+    transactionId?: string;
+}
+
 export class EntityServerClient {
     private baseUrl: string;
     private token: string;
@@ -220,6 +229,120 @@ export class EntityServerClient {
         );
     }
 
+    push<T = unknown>(
+        pushEntity: string,
+        payload: Record<string, unknown>,
+        opts: { transactionId?: string } = {},
+    ): Promise<{ ok: boolean; seq?: number; data?: T }> {
+        return this.submit<T>(pushEntity, payload, opts);
+    }
+
+    pushLogList<T = unknown>(
+        params: EntityListParams = {},
+    ): Promise<{ ok: boolean; data: T[]; total: number }> {
+        return this.list<T>("push_log", params);
+    }
+
+    registerPushDevice<T = unknown>(
+        accountSeq: number,
+        deviceId: string,
+        pushToken: string,
+        opts: RegisterPushDeviceOptions = {},
+    ): Promise<{ ok: boolean; seq?: number; data?: T }> {
+        const {
+            platform,
+            deviceType,
+            browser,
+            browserVersion,
+            pushEnabled = true,
+            transactionId,
+        } = opts;
+
+        return this.submit<T>(
+            "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<T = unknown>(
+        deviceSeq: number,
+        pushToken: string,
+        opts: { pushEnabled?: boolean; transactionId?: string } = {},
+    ): Promise<{ ok: boolean; seq?: number; data?: T }> {
+        const { pushEnabled = true, transactionId } = opts;
+        return this.submit<T>(
+            "account_device",
+            {
+                seq: deviceSeq,
+                push_token: pushToken,
+                push_enabled: pushEnabled,
+            },
+            { transactionId },
+        );
+    }
+
+    disablePushDevice<T = unknown>(
+        deviceSeq: number,
+        opts: { transactionId?: string } = {},
+    ): Promise<{ ok: boolean; seq?: number; data?: T }> {
+        return this.submit<T>(
+            "account_device",
+            {
+                seq: deviceSeq,
+                push_enabled: false,
+            },
+            { transactionId: opts.transactionId },
+        );
+    }
+
+    readRequestBody<T = Record<string, unknown>>(
+        body: ArrayBuffer | Uint8Array | string | T | null | undefined,
+        contentType = "application/json",
+        requireEncrypted = false,
+    ): T {
+        const lowered = contentType.toLowerCase();
+        const isEncrypted = lowered.includes("application/octet-stream");
+
+        if (requireEncrypted && !isEncrypted) {
+            throw new Error(
+                "Encrypted request required: Content-Type must be application/octet-stream",
+            );
+        }
+
+        if (isEncrypted) {
+            if (body == null) {
+                throw new Error("Encrypted request body is empty");
+            }
+            if (body instanceof ArrayBuffer) {
+                return this.decryptPacket<T>(body);
+            }
+            if (body instanceof Uint8Array) {
+                const sliced = body.buffer.slice(
+                    body.byteOffset,
+                    body.byteOffset + body.byteLength,
+                );
+                return this.decryptPacket<T>(sliced);
+            }
+            throw new Error(
+                "Encrypted request body must be ArrayBuffer or Uint8Array",
+            );
+        }
+
+        if (body == null || body === "") return {} as T;
+        if (typeof body === "string") return JSON.parse(body) as T;
+        return body as T;
+    }
+
     private async request<T>(
         method: string,
         path: string,

package/template/samples/react/src/hooks/useEntity.ts

@@ -103,3 +103,71 @@ export function useEntityRollback(entity: string) {
         },
     });
 }
+
+/** 푸시 디바이스 등록/갱신 */
+export function useRegisterPushDevice() {
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: (args: {
+            accountSeq: number;
+            deviceId: string;
+            pushToken: string;
+            platform?: string;
+            deviceType?: string;
+            browser?: string;
+            browserVersion?: string;
+            pushEnabled?: boolean;
+            transactionId?: string;
+        }) =>
+            entityServer.registerPushDevice(
+                args.accountSeq,
+                args.deviceId,
+                args.pushToken,
+                {
+                    platform: args.platform,
+                    deviceType: args.deviceType,
+                    browser: args.browser,
+                    browserVersion: args.browserVersion,
+                    pushEnabled: args.pushEnabled,
+                    transactionId: args.transactionId,
+                },
+            ),
+        onSuccess: () => {
+            qc.invalidateQueries({ queryKey: ["entity", "account_device"] });
+        },
+    });
+}
+
+/** 푸시 디바이스 토큰 갱신 */
+export function useUpdatePushDeviceToken() {
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: (args: {
+            deviceSeq: number;
+            pushToken: string;
+            pushEnabled?: boolean;
+            transactionId?: string;
+        }) =>
+            entityServer.updatePushDeviceToken(args.deviceSeq, args.pushToken, {
+                pushEnabled: args.pushEnabled,
+                transactionId: args.transactionId,
+            }),
+        onSuccess: () => {
+            qc.invalidateQueries({ queryKey: ["entity", "account_device"] });
+        },
+    });
+}
+
+/** 푸시 디바이스 비활성화 */
+export function useDisablePushDevice() {
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: (args: { deviceSeq: number; transactionId?: string }) =>
+            entityServer.disablePushDevice(args.deviceSeq, {
+                transactionId: args.transactionId,
+            }),
+        onSuccess: () => {
+            qc.invalidateQueries({ queryKey: ["entity", "account_device"] });
+        },
+    });
+}