feat(responses): sync query API schemas and add runtime validation

- getBalance 응답에 lowBalanceAlert, minimumCash, rechargeTo, deposit 등 실서버에 존재하는 필드를 반영해 스키마 확장
- getStatistics, getGroups, getGroup, getBlacks, getBlockGroups, getKakaoChannel, getKakaoAlimtalkTemplate(s) 응답의 드리프트(nullable, 누락 필드, Record→Array 등) 정합화
- MessageTypeRecord에 rcs_itpl/ltpl, fax, voice, bms_* 신규 메시지 타입 추가
- 조회 응답 전용 storedMessageSchema 신설해 발송용 messageSchema와 분리
- DefaultService.requestEffect/getWithQuery에 responseSchema 주입 경로 마련하고, decodeServerResponse 헬퍼 추가로 서버 응답을 런타임 검증해 드리프트 즉시 감지
- 15개 조회 서비스 메서드에 해당 스키마 연결

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Palbahngmiyine

src/lib/schemaUtils.ts

@@ -1,6 +1,10 @@
 import {ParseResult, Schema} from 'effect';
 import * as Effect from 'effect/Effect';
-import {BadRequestError, InvalidDateError} from '../errors/defaultError';
+import {
+  BadRequestError,
+  InvalidDateError,
+  ServerError,
+} from '../errors/defaultError';
 import stringDateTransfer, {formatWithTransfer} from './stringDateTransfer';
 
 /**
@@ -74,3 +78,24 @@ export const safeFinalize = <T>(
             message: error instanceof Error ? error.message : String(error),
           }),
   });
+
+/**
+ * API 응답 body를 Effect Schema로 런타임 검증하고 실패 시 ServerError로 래핑.
+ * 서버가 예고 없이 응답 구조를 바꾼 경우 소비자 측에서 조용히 undefined로 터지는 대신
+ * 스키마 불일치 위치를 즉시 파악할 수 있도록 한다.
+ */
+export const decodeServerResponse = <A, I>(
+  schema: Schema.Schema<A, I>,
+  data: unknown,
+  context?: {url?: string; httpStatus?: number},
+): Effect.Effect<A, ServerError> =>
+  Effect.mapError(
+    Schema.decodeUnknown(schema)(data),
+    err =>
+      new ServerError({
+        errorCode: 'ResponseSchemaMismatch',
+        errorMessage: ParseResult.TreeFormatter.formatErrorSync(err),
+        httpStatus: context?.httpStatus ?? 200,
+        url: context?.url,
+      }),
+  );

src/models/base/kakao/kakaoChannel.ts

@@ -21,7 +21,7 @@ export const kakaoChannelSchema = Schema.Struct({
   channelId: Schema.String,
   searchId: Schema.String,
   accountId: Schema.String,
-  phoneNumber: Schema.String,
+  phoneNumber: Schema.optional(Schema.String),
   sharedAccountIds: Schema.Array(Schema.String),
   dateCreated: Schema.optional(
     Schema.Union(Schema.String, Schema.DateFromSelf),
@@ -40,7 +40,7 @@ export type KakaoChannel = {
   channelId: string;
   searchId: string;
   accountId: string;
-  phoneNumber: string;
+  phoneNumber?: string;
   sharedAccountIds: ReadonlyArray<string>;
   dateCreated?: Date;
   dateUpdated?: Date;
@@ -63,6 +63,6 @@ export function decodeKakaoChannel(
       sharedAccountIds: data.sharedAccountIds,
       dateCreated,
       dateUpdated,
-    };
+    } satisfies KakaoChannel;
   });
 }

src/models/base/messages/storedMessage.ts

@@ -0,0 +1,59 @@
+import {Schema} from 'effect';
+import {messageTypeSchema} from './message';
+
+/**
+ * 조회 응답(getMessages/getGroupMessages)에 포함된 메시지 아이템 스키마.
+ *
+ * 발송용 messageSchema와 달리 서버가 저장해둔 값을 그대로 반환하므로
+ * - optional 필드 상당수가 null로 내려올 수 있다.
+ * - kakaoOptions/rcsOptions 등 내부 구조가 발송 요청과 다르다(서버 정규화 포맷).
+ *
+ * 따라서 핵심 필드만 선언하고, 나머지는 런타임 통과를 위해 NullishOr/Unknown으로 관대하게 허용한다.
+ * Schema.Struct는 기본적으로 extra 필드를 무시하므로 신규 필드 추가 시에도 drift 없이 통과한다.
+ */
+export const storedMessageSchema = Schema.Struct({
+  messageId: Schema.optional(Schema.String),
+  type: Schema.NullishOr(messageTypeSchema),
+  to: Schema.optional(Schema.Union(Schema.String, Schema.Array(Schema.String))),
+  from: Schema.NullishOr(Schema.String),
+  text: Schema.NullishOr(Schema.String),
+  imageId: Schema.NullishOr(Schema.String),
+  subject: Schema.NullishOr(Schema.String),
+  country: Schema.NullishOr(Schema.String),
+  accountId: Schema.optional(Schema.String),
+  groupId: Schema.optional(Schema.String),
+  status: Schema.NullishOr(Schema.String),
+  statusCode: Schema.NullishOr(Schema.String),
+  reason: Schema.NullishOr(Schema.String),
+  networkName: Schema.NullishOr(Schema.String),
+  networkCode: Schema.NullishOr(Schema.String),
+  customFields: Schema.optional(
+    Schema.NullishOr(Schema.Record({key: Schema.String, value: Schema.String})),
+  ),
+  autoTypeDetect: Schema.optional(Schema.Union(Schema.Boolean, Schema.Number)),
+  replacement: Schema.optional(Schema.Union(Schema.Boolean, Schema.Number)),
+  resendCount: Schema.optional(Schema.Number),
+  dateCreated: Schema.optional(Schema.String),
+  dateUpdated: Schema.optional(Schema.String),
+  dateProcessed: Schema.NullishOr(Schema.String),
+  dateReceived: Schema.NullishOr(Schema.String),
+  dateReported: Schema.NullishOr(Schema.String),
+  kakaoOptions: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  rcsOptions: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  naverOptions: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  faxOptions: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  voiceOptions: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  replacements: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  log: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  queues: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  currentQueue: Schema.optional(Schema.NullishOr(Schema.Unknown)),
+  clusterKey: Schema.NullishOr(Schema.String),
+  unavailableSenderNumber: Schema.optional(
+    Schema.Union(Schema.Boolean, Schema.Number),
+  ),
+  faxPageCount: Schema.optional(Schema.Number),
+  voiceDuration: Schema.optional(Schema.Number),
+  voiceReplied: Schema.optional(Schema.Union(Schema.Boolean, Schema.Number)),
+  _id: Schema.optional(Schema.String),
+});
+export type StoredMessage = Schema.Schema.Type<typeof storedMessageSchema>;

src/models/index.ts

@@ -65,6 +65,10 @@ export {
   messageSchema,
   messageTypeSchema,
 } from './base/messages/message';
+export {
+  type StoredMessage,
+  storedMessageSchema,
+} from './base/messages/storedMessage';
 export {
   type NaverOptionSchema,
   naverOptionSchema,

src/models/responses/iam/getBlacksResponse.ts

@@ -1,11 +1,11 @@
-import {blackSchema, handleKeySchema} from '@internal-types/commonTypes';
+import {blackSchema} from '@internal-types/commonTypes';
 import {Schema} from 'effect';
 
 export const getBlacksResponseSchema = Schema.Struct({
   startKey: Schema.NullishOr(Schema.String),
   limit: Schema.Number,
   nextKey: Schema.NullishOr(Schema.String),
-  blackList: Schema.Record({key: handleKeySchema, value: blackSchema}),
+  blackList: Schema.Array(blackSchema),
 });
 export type GetBlacksResponse = Schema.Schema.Type<
   typeof getBlacksResponseSchema

src/models/responses/kakao/getKakaoTemplateResponse.ts

@@ -9,7 +9,7 @@ export const getKakaoTemplateResponseSchema = kakaoAlimtalkTemplateSchema.pipe(
   Schema.extend(
     Schema.Struct({
       assignType: kakaoAlimtalkTemplateAssignTypeSchema,
-      accountId: Schema.String,
+      accountId: Schema.NullishOr(Schema.String),
       commentable: Schema.Boolean,
       dateCreated: Schema.String,
       dateUpdated: Schema.String,

src/models/responses/messageResponses.ts

@@ -6,10 +6,9 @@ import {
   groupIdSchema,
   groupSchema,
   logSchema,
-  messageTypeRecordSchema,
 } from '@internal-types/commonTypes';
 import {Schema} from 'effect';
-import {messageSchema} from '../base/messages/message';
+import {storedMessageSchema} from '../base/messages/storedMessage';
 
 export const groupMessageResponseSchema = Schema.Struct({
   count: countSchema,
@@ -28,9 +27,9 @@ export const groupMessageResponseSchema = Schema.Struct({
   price: Schema.Record({key: Schema.String, value: Schema.Unknown}),
   dateCreated: Schema.String,
   dateUpdated: Schema.String,
-  scheduledDate: Schema.optional(Schema.String),
-  dateSent: Schema.optional(Schema.String),
-  dateCompleted: Schema.optional(Schema.String),
+  scheduledDate: Schema.NullishOr(Schema.String),
+  dateSent: Schema.NullishOr(Schema.String),
+  dateCompleted: Schema.NullishOr(Schema.String),
 });
 export type GroupMessageResponse = Schema.Schema.Type<
   typeof groupMessageResponseSchema
@@ -62,10 +61,10 @@ export type AddMessageResponse = Schema.Schema.Type<
 >;
 
 export const getMessagesResponseSchema = Schema.Struct({
-  startKey: Schema.NullOr(Schema.String),
-  nextKey: Schema.NullOr(Schema.String),
+  startKey: Schema.optional(Schema.NullOr(Schema.String)),
+  nextKey: Schema.optional(Schema.NullOr(Schema.String)),
   limit: Schema.Number,
-  messageList: Schema.Record({key: Schema.String, value: messageSchema}),
+  messageList: Schema.Record({key: Schema.String, value: storedMessageSchema}),
 });
 export type GetMessagesResponse = Schema.Schema.Type<
   typeof getMessagesResponseSchema
@@ -108,21 +107,37 @@ const statisticsPeriodResultSchema = Schema.Struct({
   rcs_lms: Schema.Number,
   rcs_mms: Schema.Number,
   rcs_tpl: Schema.Number,
+  rcs_itpl: Schema.optional(Schema.Number),
+  rcs_ltpl: Schema.optional(Schema.Number),
+  fax: Schema.optional(Schema.Number),
+  voice: Schema.optional(Schema.Number),
+  bms_text: Schema.optional(Schema.Number),
+  bms_image: Schema.optional(Schema.Number),
+  bms_wide: Schema.optional(Schema.Number),
+  bms_wide_item_list: Schema.optional(Schema.Number),
+  bms_carousel_feed: Schema.optional(Schema.Number),
+  bms_premium_video: Schema.optional(Schema.Number),
+  bms_commerce: Schema.optional(Schema.Number),
+  bms_carousel_commerce: Schema.optional(Schema.Number),
+  bms_free: Schema.optional(Schema.Number),
 });
 
 const refundSchema = Schema.Struct({
   balance: Schema.Number,
   point: Schema.Number,
+  deposit: Schema.optional(Schema.Number),
 });
 
 const dayPeriodSchema = Schema.Struct({
   _id: Schema.String,
   month: Schema.String,
+  date: Schema.optional(Schema.String),
   balance: Schema.Number,
   point: Schema.Number,
+  deposit: Schema.optional(Schema.Number),
   statusCode: Schema.Record({
     key: Schema.String,
-    value: messageTypeRecordSchema,
+    value: Schema.Record({key: Schema.String, value: Schema.Number}),
   }),
   refund: refundSchema,
   total: statisticsPeriodResultSchema,
@@ -135,6 +150,8 @@ const monthPeriodRefundSchema = Schema.Struct({
   balanceAvg: Schema.Number,
   point: Schema.Number,
   pointAvg: Schema.Number,
+  deposit: Schema.optional(Schema.Number),
+  depositAvg: Schema.optional(Schema.Number),
 });
 
 const monthPeriodSchema = Schema.Struct({
@@ -143,8 +160,10 @@ const monthPeriodSchema = Schema.Struct({
   balanceAvg: Schema.Number,
   point: Schema.Number,
   pointAvg: Schema.Number,
+  deposit: Schema.optional(Schema.Number),
+  depositAvg: Schema.optional(Schema.Number),
   dayPeriod: Schema.Array(dayPeriodSchema),
-  refund: monthPeriodRefundSchema,
+  refund: Schema.optional(monthPeriodRefundSchema),
   total: statisticsPeriodResultSchema,
   successed: statisticsPeriodResultSchema,
   failed: statisticsPeriodResultSchema,
@@ -153,25 +172,44 @@ const monthPeriodSchema = Schema.Struct({
 export const getStatisticsResponseSchema = Schema.Struct({
   balance: Schema.Number,
   point: Schema.Number,
+  deposit: Schema.optional(Schema.Number),
   monthlyBalanceAvg: Schema.Number,
   monthlyPointAvg: Schema.Number,
+  monthlyDepositAvg: Schema.optional(Schema.Number),
   monthPeriod: Schema.Array(monthPeriodSchema),
   total: statisticsPeriodResultSchema,
   successed: statisticsPeriodResultSchema,
   failed: statisticsPeriodResultSchema,
-  dailyBalanceAvg: Schema.Number,
-  dailyPointAvg: Schema.Number,
-  dailyTotalCountAvg: Schema.Number,
-  dailyFailedCountAvg: Schema.Number,
-  dailySuccessedCountAvg: Schema.Number,
+  dailyBalanceAvg: Schema.optional(Schema.Number),
+  dailyPointAvg: Schema.optional(Schema.Number),
+  dailyTotalCountAvg: Schema.optional(Schema.Number),
+  dailyFailedCountAvg: Schema.optional(Schema.Number),
+  dailySuccessedCountAvg: Schema.optional(Schema.Number),
 });
 export type GetStatisticsResponse = Schema.Schema.Type<
   typeof getStatisticsResponseSchema
 >;
 
+const lowBalanceAlertSchema = Schema.Struct({
+  notificationBalance: Schema.String,
+  currentBalance: Schema.String,
+  balances: Schema.Array(Schema.Number),
+  channels: Schema.Array(Schema.String),
+  enabled: Schema.Boolean,
+});
+export type LowBalanceAlert = Schema.Schema.Type<typeof lowBalanceAlertSchema>;
+
 export const getBalanceResponseSchema = Schema.Struct({
-  balance: Schema.Number,
+  lowBalanceAlert: Schema.optional(lowBalanceAlertSchema),
   point: Schema.Number,
+  minimumCash: Schema.optional(Schema.Number),
+  rechargeTo: Schema.optional(Schema.Number),
+  rechargeTryCount: Schema.optional(Schema.Number),
+  autoRecharge: Schema.optional(Schema.Number),
+  accountId: Schema.optional(Schema.String),
+  balance: Schema.Number,
+  deposit: Schema.optional(Schema.Number),
+  balanceOnly: Schema.optional(Schema.Number),
 });
 export type GetBalanceResponse = Schema.Schema.Type<
   typeof getBalanceResponseSchema

src/services/cash/cashService.ts

@@ -1,5 +1,8 @@
 import {runSafePromise} from '@lib/effectErrorHandler';
-import {type GetBalanceResponse} from '@models/responses/messageResponses';
+import {
+  type GetBalanceResponse,
+  getBalanceResponseSchema,
+} from '@models/responses/messageResponses';
 import DefaultService from '../defaultService';
 
 export default class CashService extends DefaultService {
@@ -12,6 +15,7 @@ export default class CashService extends DefaultService {
       this.requestEffect<never, GetBalanceResponse>({
         httpMethod: 'GET',
         url: 'cash/v1/balance',
+        responseSchema: getBalanceResponseSchema,
       }),
     );
   }