@sayren/store-sdk 0.1.0 → 0.2.0

package/src/client.ts

@@ -1,6 +1,17 @@
 import { z } from "zod";
 import { base64Utf8 } from "./base64";
 import { createHttp, path, type Query, resolveToken, type TokenSource, unwrapData } from "./http";
+import {
+  type AnalyticsProductsParams,
+  type AnalyticsRangeParams,
+  type AnalyticsSourcesParams,
+  analyticsOverviewSchema,
+  analyticsProductsQuerySchema,
+  analyticsProductsSchema,
+  analyticsRangeQuerySchema,
+  analyticsSourcesQuerySchema,
+  analyticsSourcesSchema,
+} from "./schemas/analytics";
 import {
   type ApiClientListParams,
   apiClientSchema,
@@ -34,8 +45,9 @@ import {
 import {
   approveClaimResultSchema,
   type ClaimListParams,
+  claimDetailSchema,
+  claimHoldResultSchema,
   claimSchema,
-  claimStatusSchema,
   type RejectClaimRequest,
   rejectClaimRequestSchema,
 } from "./schemas/claim";
@@ -47,8 +59,8 @@ import {
   reviewSchema,
   type SettlementListParams,
   sellerCustomerInquirySchema,
-  settlementDetailSchema,
   settlementSummarySchema,
+  settlementWithDetailsSchema,
   type WebhookDeliveryListParams,
   type WebhookRequest,
   type WebhookTestRequest,
@@ -64,9 +76,11 @@ import {
 import {
   type CancelBySellerRequest,
   cancelBySellerRequestSchema,
+  cancelBySellerResultSchema,
   carrierSchema,
   type DispatchRequest,
   deliveryInfoSchema,
+  deliveryStatusSchema,
   dispatchRequestSchema,
   type HoldOrderItemRequest,
   holdOrderItemRequestSchema,
@@ -75,6 +89,7 @@ import {
   orderItemSchema,
   orderSchema,
   orderSummarySchema,
+  purchaseDecisionExtendResultSchema,
 } from "./schemas/order";
 import {
   type PaymentListParams,
@@ -459,11 +474,7 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request(
           "POST",
           path`/order-items/${orderItemId}/cancel`,
-          z.object({
-            orderItemId: z.string(),
-            refundAmount: z.number().int(),
-            refundedAt: z.string(),
-          }),
+          cancelBySellerResultSchema,
           { body: cancelBySellerRequestSchema.parse(body), headers: idempotency(idempotencyKey) },
         ),
       updateMemo: (orderItemId: string, memo: string) =>
@@ -474,11 +485,7 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request(
           "POST",
           path`/order-items/${orderItemId}/purchase-decision/extend`,
-          z.object({
-            orderItemId: z.string(),
-            autoDecisionDate: z.string(),
-            extendCount: z.number().int().max(2),
-          }),
+          purchaseDecisionExtendResultSchema,
         ),
       dispatch: (orderItemId: string, body: DispatchRequest, idempotencyKey?: string) =>
         storeHttp.request("POST", path`/order-items/${orderItemId}/dispatch`, deliveryInfoSchema, {
@@ -498,15 +505,7 @@ export function createStoreClient(options: StoreClientOptions) {
           body: { carrierCode, trackingNumber },
         }),
       getDelivery: (orderItemId: string) =>
-        storeHttp.request(
-          "GET",
-          path`/order-items/${orderItemId}/delivery`,
-          deliveryInfoSchema.extend({
-            trackingEvents: z
-              .array(z.object({ status: z.string(), location: z.string(), occurredAt: z.string() }))
-              .optional(),
-          }),
-        ),
+        storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema),
     },
 
     carriers: {
@@ -517,21 +516,7 @@ export function createStoreClient(options: StoreClientOptions) {
       list: (params?: ClaimListParams) =>
         storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: params as Query }),
       get: (claimId: string) =>
-        storeHttp.request(
-          "GET",
-          path`/claims/${claimId}`,
-          claimSchema.extend({
-            histories: z
-              .array(
-                z.object({
-                  status: claimStatusSchema,
-                  actor: z.enum(["BUYER", "SELLER", "SYSTEM"]),
-                  occurredAt: z.string(),
-                }),
-              )
-              .optional(),
-          }),
-        ),
+        storeHttp.request("GET", path`/claims/${claimId}`, claimDetailSchema),
       approve: (claimId: string, deductAmount?: number, idempotencyKey?: string) =>
         storeHttp.request("POST", path`/claims/${claimId}/approve`, approveClaimResultSchema, {
           body: deductAmount !== undefined ? { deductAmount } : {},
@@ -552,12 +537,9 @@ export function createStoreClient(options: StoreClientOptions) {
           body: { carrierCode, trackingNumber },
         }),
       hold: (claimId: string, reason: string) =>
-        storeHttp.request(
-          "POST",
-          path`/claims/${claimId}/hold`,
-          z.object({ claimId: z.string(), holdExpiresAt: z.string() }),
-          { body: { reason } },
-        ),
+        storeHttp.request("POST", path`/claims/${claimId}/hold`, claimHoldResultSchema, {
+          body: { reason },
+        }),
       releaseHold: (claimId: string) =>
         storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`),
     },
@@ -614,12 +596,9 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       /** @deprecated `salesReport.get`을 쓴다. 기존 정산 레코드 조회만 유지된다 */
       get: (settlementId: string, params?: PageParams) =>
-        storeHttp.request(
-          "GET",
-          path`/settlements/${settlementId}`,
-          settlementSummarySchema.extend({ details: z.array(settlementDetailSchema).optional() }),
-          { query: params as Query },
-        ),
+        storeHttp.request("GET", path`/settlements/${settlementId}`, settlementWithDetailsSchema, {
+          query: params as Query,
+        }),
     },
 
     /**
@@ -638,6 +617,29 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
     },
 
+    /**
+     * 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+     * 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
+     * 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
+     */
+    analytics: {
+      /** `GET /v1/analytics/overview` — 합계·세션 퍼널·날짜별 값 */
+      overview: (params: AnalyticsRangeParams) =>
+        storeHttp.request("GET", "/analytics/overview", analyticsOverviewSchema, {
+          query: analyticsRangeQuerySchema.parse(params),
+        }),
+      /** `GET /v1/analytics/products` — 상품별 노출·조회·장바구니·구매 */
+      products: (params: AnalyticsProductsParams) =>
+        storeHttp.request("GET", "/analytics/products", analyticsProductsSchema, {
+          query: analyticsProductsQuerySchema.parse(params) as unknown as Query,
+        }),
+      /** `GET /v1/analytics/sources` — 채널·소스·캠페인·기기별 세션과 구매 */
+      sources: (params: AnalyticsSourcesParams) =>
+        storeHttp.request("GET", "/analytics/sources", analyticsSourcesSchema, {
+          query: analyticsSourcesQuerySchema.parse(params),
+        }),
+    },
+
     /**
      * 결제 내역 — 스코프 `settlement:r`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
      * 결제(카드 거절·결제창 이탈·승인 결과 확인 중)도 그대로 나온다.

package/src/index.ts

@@ -11,6 +11,7 @@ export {
   oauthTokenResponseSchema,
   refreshUserToken,
 } from "./oauth";
+export * from "./schemas/analytics";
 export * from "./schemas/api-client";
 export * from "./schemas/api-log";
 export * from "./schemas/auth";

package/src/schemas/analytics.ts

@@ -0,0 +1,200 @@
+import { z } from "zod";
+
+/**
+ * 방문 분석 조회 (관리 API `/v1/analytics/*`, 스코프 `analytics:r`).
+ *
+ * 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
+ * 갱신되므로 오늘 값은 `lastComputedAt` 시점까지 반영돼 있다. 봇·자동화 브라우저의 세션은 모든 집계에서 빠진다.
+ */
+
+const reportDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "날짜 형식은 YYYY-MM-DD 입니다");
+
+const includeTest = z
+  .enum(["true", "false"])
+  .optional()
+  .describe("테스트 결제(샌드박스 결제)로 만든 구매 포함 여부. 기본 `false`");
+
+export const analyticsRangeQuerySchema = z.object({
+  from: reportDate.describe("시작일 (YYYY-MM-DD, Asia/Seoul 기준, 포함)"),
+  to: reportDate.describe("종료일 (YYYY-MM-DD, 포함). from부터 최대 92일"),
+  includeTest,
+});
+export type AnalyticsRangeParams = z.infer<typeof analyticsRangeQuerySchema>;
+
+const rangeMeta = {
+  from: z.string(),
+  to: z.string(),
+  timezone: z.literal("Asia/Seoul"),
+  currency: z.literal("KRW"),
+  includeTest: z.boolean().describe("테스트 결제 구매를 포함했는가"),
+  lastComputedAt: z
+    .string()
+    .nullable()
+    .describe("기간 안에서 가장 최근에 집계한 시각(ISO 8601). 집계된 날이 없으면 null"),
+};
+
+/**
+ * 비율(0 이상). 단계가 세션 안에서 꼭 이어지지는 않아 1을 넘을 수 있다 — 예: 조회 없이 장바구니에서 바로 산 구매,
+ * 자정을 넘겨 다음 날 확정된 구매.
+ */
+const rate = (description: string) => z.number().min(0).nullable().describe(description);
+
+export const analyticsTotalsSchema = z.object({
+  visitors: z
+    .number()
+    .int()
+    .describe("방문자 수 — 날짜별 순방문자의 합. 여러 날 방문한 사람은 날마다 센다"),
+  sessions: z
+    .number()
+    .int()
+    .describe("세션 수. 30분 동안 활동이 없거나 다른 캠페인으로 들어오면 새 세션"),
+  engagedSessions: z
+    .number()
+    .int()
+    .describe(
+      "참여 세션 수 — 페이지뷰 2개 이상, 체류 10초 이상, 장바구니 담기·결제 시작·구매 중 하나",
+    ),
+  pageViews: z.number().int(),
+  engagementSeconds: z
+    .number()
+    .int()
+    .describe(
+      "페이지가 화면에 보인 시간의 합(초). 페이지뷰 하나는 최대 30분, 세션은 세션 길이 + 30분까지 센다",
+    ),
+  productViews: z.number().int().describe("상품 조회 수"),
+  productViewSessions: z.number().int().describe("상품을 조회한 세션 수"),
+  addToCartSessions: z.number().int().describe("장바구니에 담은 세션 수"),
+  beginCheckoutSessions: z.number().int().describe("주문서를 연 세션 수"),
+  purchaseSessions: z.number().int().describe("구매한 세션 수"),
+  purchases: z.number().int().describe("구매(주문) 수"),
+  revenue: z
+    .number()
+    .int()
+    .describe(
+      "구매 금액 합계 — 주문 결제 금액(배송비 포함). 이후 취소·환불은 빼지 않으므로 매출 리포트의 순매출과 다르다",
+    ),
+  engagementRate: rate("참여율 = 참여 세션 / 세션. 세션이 없으면 null"),
+  conversionRate: rate("전환율 = 구매 세션 / 세션. 세션이 없으면 null"),
+});
+export type AnalyticsTotals = z.infer<typeof analyticsTotalsSchema>;
+
+export const analyticsFunnelStepSchema = z.object({
+  step: z.enum(["SESSION", "PRODUCT_VIEW", "ADD_TO_CART", "BEGIN_CHECKOUT", "PURCHASE"]),
+  sessions: z.number().int(),
+  rateFromPrevious: rate("직전 단계 대비 비율. 첫 단계이거나 직전 단계가 0이면 null"),
+});
+export type AnalyticsFunnelStep = z.infer<typeof analyticsFunnelStepSchema>;
+
+export const analyticsOverviewSchema = z.object({
+  ...rangeMeta,
+  summary: analyticsTotalsSchema.describe("기간 합계"),
+  funnel: z
+    .array(analyticsFunnelStepSchema)
+    .describe(
+      "세션 기준 구매 퍼널. 각 단계는 그 행동을 한 세션 수이고, 앞 단계를 거쳤는지는 따지지 않는다",
+    ),
+  rows: z
+    .array(analyticsTotalsSchema.extend({ date: z.string().describe("일자 (YYYY-MM-DD)") }))
+    .describe("날짜별 값. 세션이 없는 날은 생략된다"),
+});
+export type AnalyticsOverview = z.infer<typeof analyticsOverviewSchema>;
+
+export const analyticsProductSortSchema = z
+  .enum(["VIEWS", "ADD_TO_CARTS", "PURCHASES", "REVENUE", "IMPRESSIONS"])
+  .describe("정렬 기준(내림차순). 기본 `VIEWS`");
+export type AnalyticsProductSort = z.infer<typeof analyticsProductSortSchema>;
+
+export const analyticsProductsQuerySchema = analyticsRangeQuerySchema.extend({
+  sort: analyticsProductSortSchema.optional(),
+  limit: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("최대 행 수. 기본 20, 최대 100"),
+});
+export type AnalyticsProductsParams = z.infer<typeof analyticsProductsQuerySchema>;
+
+export const analyticsProductRowSchema = z.object({
+  productId: z.string(),
+  productName: z.string().nullable().describe("현재 상품명. 삭제된 상품이면 null"),
+  impressions: z.number().int().describe("목록 노출 수"),
+  views: z.number().int().describe("상세 조회 수"),
+  viewSessions: z.number().int().describe("상세를 조회한 세션 수"),
+  addToCarts: z.number().int().describe("장바구니 담기 수"),
+  purchases: z.number().int().describe("이 상품이 포함된 구매(주문) 수"),
+  quantity: z.number().int().describe("구매 수량"),
+  revenue: z
+    .number()
+    .int()
+    .describe(
+      "이 상품의 구매 금액 — 주문 상품 금액(할인 반영, 배송비 제외) 합계. 이후 취소·환불은 빼지 않는다",
+    ),
+  purchaseRate: rate("구매율 = 구매 / 조회 세션. 조회 세션이 없으면 null"),
+});
+export type AnalyticsProductRow = z.infer<typeof analyticsProductRowSchema>;
+
+export const analyticsProductsSchema = z.object({
+  ...rangeMeta,
+  sort: analyticsProductSortSchema,
+  rows: z.array(analyticsProductRowSchema),
+});
+export type AnalyticsProducts = z.infer<typeof analyticsProductsSchema>;
+
+export const analyticsChannelSchema = z
+  .enum(["DIRECT", "ORGANIC_SEARCH", "SOCIAL", "PAID", "EMAIL", "CAMPAIGN", "REFERRAL", "UNKNOWN"])
+  .describe(
+    "유입 채널 — 세션 첫 페이지뷰의 utm·리퍼러로 정한다. " +
+      "`PAID`(utm_medium이 cpc·ppc·paid·display 등), `EMAIL`(utm_medium email), `SOCIAL`(SNS 리퍼러·utm_source), " +
+      "`ORGANIC_SEARCH`(검색 엔진 리퍼러), `CAMPAIGN`(그 밖의 utm), `REFERRAL`(그 밖의 리퍼러), `DIRECT`(없음), " +
+      "`UNKNOWN`(페이지뷰 없이 서버 이벤트만 있는 세션)",
+  );
+export type AnalyticsChannel = z.infer<typeof analyticsChannelSchema>;
+
+export const analyticsSourceGroupBySchema = z
+  .enum(["CHANNEL", "SOURCE", "CAMPAIGN", "DEVICE"])
+  .describe("행 집계 기준. 기본 `CHANNEL`");
+export type AnalyticsSourceGroupBy = z.infer<typeof analyticsSourceGroupBySchema>;
+
+export const analyticsSourcesQuerySchema = analyticsRangeQuerySchema.extend({
+  groupBy: analyticsSourceGroupBySchema.optional(),
+});
+export type AnalyticsSourcesParams = z.infer<typeof analyticsSourcesQuerySchema>;
+
+export const analyticsSourceRowSchema = z.object({
+  channel: analyticsChannelSchema.nullable().describe("groupBy=CHANNEL일 때만 값"),
+  source: z
+    .string()
+    .nullable()
+    .describe(
+      "groupBy=SOURCE·CAMPAIGN일 때 값. utm_source, 없으면 리퍼러 호스트, 둘 다 없으면 `(direct)`",
+    ),
+  medium: z
+    .string()
+    .nullable()
+    .describe("groupBy=SOURCE·CAMPAIGN일 때 값. utm_medium, 없으면 `referral`·`(none)`"),
+  campaign: z
+    .string()
+    .nullable()
+    .describe("groupBy=CAMPAIGN일 때 값. utm_campaign, 없으면 `(not set)`"),
+  device: z
+    .enum(["desktop", "mobile", "tablet", "unknown"])
+    .nullable()
+    .describe("groupBy=DEVICE일 때만 값"),
+  sessions: z.number().int(),
+  visitors: z.number().int().describe("날짜별 순방문자의 합"),
+  engagedSessions: z.number().int(),
+  purchaseSessions: z.number().int(),
+  purchases: z.number().int(),
+  revenue: z.number().int(),
+  conversionRate: rate("전환율 = 구매 세션 / 세션"),
+});
+export type AnalyticsSourceRow = z.infer<typeof analyticsSourceRowSchema>;
+
+export const analyticsSourcesSchema = z.object({
+  ...rangeMeta,
+  groupBy: analyticsSourceGroupBySchema,
+  rows: z.array(analyticsSourceRowSchema).describe("세션 수 내림차순"),
+});
+export type AnalyticsSources = z.infer<typeof analyticsSourcesSchema>;

package/src/schemas/category.ts

@@ -96,3 +96,39 @@ export type CategoryPatchRequest = z.infer<typeof categoryPatchRequestSchema>;
 export const categoryDeleteStrategySchema = z.enum(["reparent", "cascade"]);
 
 export type CategoryDeleteStrategy = z.infer<typeof categoryDeleteStrategySchema>;
+
+/**
+ * `GET /v1/categories` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 응답 형태가 쿼리로 갈린다:
+ * `q`가 있으면 검색 결과(`CategorySearchResult[]`), 아니면 `tree=true`일 때 트리(`CategoryTreeNode[]`),
+ * 둘 다 아니면 목록(`Category[]`)이다.
+ */
+export const categoryListQuerySchema = z.object({
+  parentId: z
+    .string()
+    .optional()
+    .describe("이 카테고리의 직계 자식만. 생략하면 최상위 카테고리. `flat=true`면 무시"),
+  flat: z
+    .enum(["true", "false"])
+    .optional()
+    .describe("`true`면 전체 카테고리를 깊이·순서대로 평탄화"),
+  tree: z
+    .enum(["true", "false"])
+    .optional()
+    .describe("`true`면 최상위부터 `children`을 채운 트리(`CategoryTreeNode[]`)를 돌려준다"),
+  q: z
+    .string()
+    .optional()
+    .describe(
+      "이름 검색(포함, 대소문자 무시). 주면 `fullPath`·`ancestors`가 붙은 검색 결과를 돌려준다",
+    ),
+});
+
+/** `DELETE /v1/categories/{categoryId}` 쿼리 — OpenAPI 문서용 형태 */
+export const categoryDeleteQuerySchema = z.object({
+  strategy: categoryDeleteStrategySchema
+    .optional()
+    .describe(
+      "하위 카테고리·연결 상품 처리 방식. 생략하면 둘 중 하나라도 있을 때 409 `CATEGORY_NOT_EMPTY`다. " +
+        "`reparent`는 직계 자식을 삭제할 카테고리의 부모로 옮기고, `cascade`는 서브트리를 삭제하고 연결 상품을 미분류로 둔다",
+    ),
+});

package/src/schemas/claim.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { PageParams } from "./common";
+import { type PageParams, pageQueryShape } from "./common";
 
 export const claimTypeSchema = z.enum(["CANCEL", "RETURN", "EXCHANGE"]);
 
@@ -65,6 +65,36 @@ export interface ClaimListParams extends PageParams {
   requestedTo?: string;
 }
 
+/** `GET /v1/claims` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+export const claimListQuerySchema = z.object({
+  type: claimTypeSchema.optional().describe("클레임 유형 필터"),
+  status: claimStatusSchema.optional().describe("클레임 상태 필터"),
+  orderItemId: z.string().optional().describe("주문상품 id 필터"),
+  requestedFrom: z.string().optional().describe("요청 시각 조회 시작 (ISO 8601, 포함)"),
+  requestedTo: z.string().optional().describe("요청 시각 조회 끝 (ISO 8601, 포함)"),
+  ...pageQueryShape(),
+});
+
+/** `GET /v1/claims/{claimId}` 응답 — 클레임 + 상태 이력 */
+export const claimDetailSchema = claimSchema.extend({
+  histories: z
+    .array(
+      z.object({
+        status: claimStatusSchema,
+        actor: z.enum(["BUYER", "SELLER", "SYSTEM"]),
+        occurredAt: z.string(),
+      }),
+    )
+    .optional(),
+});
+
+export type ClaimDetail = z.infer<typeof claimDetailSchema>;
+
+/** `POST /v1/claims/{claimId}/hold` 응답 */
+export const claimHoldResultSchema = z.object({ claimId: z.string(), holdExpiresAt: z.string() });
+
+export type ClaimHoldResult = z.infer<typeof claimHoldResultSchema>;
+
 export const rejectClaimRequestSchema = z.object({
   reason: z.enum([
     "USED_PRODUCT",

package/src/schemas/common.ts

@@ -13,6 +13,18 @@ export function pageSchema<T extends z.ZodType>(item: T) {
   return pageInfoSchema.extend({ contents: z.array(item) });
 }
 
+/**
+ * 목록 쿼리의 `page`·`size` — OpenAPI 문서용 형태(값은 쿼리 문자열). 서버는 숫자가 아니거나 범위를 벗어난
+ * 값을 기본값·상한으로 보정한다.
+ */
+export function pageQueryShape(options: { defaultSize?: number; maxSize?: number } = {}) {
+  const { defaultSize = 20, maxSize = 100 } = options;
+  return {
+    page: z.string().optional().describe("페이지 번호 (1부터, 기본 1)"),
+    size: z.string().optional().describe(`페이지 크기 (기본 ${defaultSize}, 최대 ${maxSize})`),
+  };
+}
+
 export interface PageParams {
   page?: number;
   size?: number;

package/src/schemas/misc.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { PageParams } from "./common";
+import { type PageParams, pageQueryShape } from "./common";
 
 export const inquirySchema = z.object({
   inquiryId: z.string(),
@@ -54,6 +54,27 @@ export const sellerCustomerInquirySchema = z.object({
 
 export type SellerCustomerInquiry = z.infer<typeof sellerCustomerInquirySchema>;
 
+const answeredQuery = z
+  .enum(["true", "false"])
+  .optional()
+  .describe("답변 여부 필터. `true`면 답변된 문의만, `false`면 미답변만, 생략하면 전부");
+
+/** `GET /v1/inquiries` 쿼리(상품 문의) — OpenAPI 문서용 형태(값은 쿼리 문자열). 최신순이다 */
+export const inquiryListQuerySchema = z.object({
+  answered: answeredQuery,
+  productId: z.string().optional().describe("상품 id 필터"),
+  from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
+  ...pageQueryShape(),
+});
+
+/** `GET /v1/customer-inquiries` 쿼리(1:1 문의) — OpenAPI 문서용 형태(값은 쿼리 문자열). 최신순이다 */
+export const customerInquiryListQuerySchema = z.object({
+  answered: answeredQuery,
+  category: customerInquiryCategorySchema.optional().describe("문의 유형 필터"),
+  from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
+  ...pageQueryShape(),
+});
+
 export const settlementStatusSchema = z.enum(["SCHEDULED", "PAID", "HELD"]);
 
 export type SettlementStatus = z.infer<typeof settlementStatusSchema>;
@@ -88,6 +109,29 @@ export const settlementDetailSchema = z.object({
 
 export type SettlementDetail = z.infer<typeof settlementDetailSchema>;
 
+/** `GET /v1/settlements/{settlementId}` 응답 — 정산 요약 + 상세 내역(`size`건까지) */
+export const settlementWithDetailsSchema = settlementSummarySchema.extend({
+  details: z.array(settlementDetailSchema).optional(),
+});
+
+export type SettlementWithDetails = z.infer<typeof settlementWithDetailsSchema>;
+
+/** `GET /v1/settlements` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 정산일 최신순이다 */
+export const settlementListQuerySchema = z.object({
+  from: z.string().describe("정산일 조회 시작 (ISO 8601, 포함). 필수"),
+  to: z
+    .string()
+    .optional()
+    .describe("정산일 조회 끝 (ISO 8601, 포함). 생략하면 from부터 31일. 기간은 최대 31일"),
+  status: settlementStatusSchema.optional().describe("정산 상태 필터"),
+  ...pageQueryShape(),
+});
+
+/** `GET /v1/settlements/{settlementId}` 쿼리 — `size`는 돌려줄 상세 내역 건수다(`page`는 무시) */
+export const settlementDetailQuerySchema = z.object(
+  pageQueryShape({ defaultSize: 100, maxSize: 300 }),
+);
+
 export interface SettlementListParams extends PageParams {
   from: string;
   to?: string;
@@ -288,11 +332,42 @@ export const reviewSchema = z.object({
 
 export type Review = z.infer<typeof reviewSchema>;
 
+export const reviewSortSchema = z.enum([
+  "createdAt.desc",
+  "createdAt.asc",
+  "rating.asc",
+  "rating.desc",
+]);
+
+export type ReviewSort = z.infer<typeof reviewSortSchema>;
+
 export interface ReviewListParams extends PageParams {
   productId?: string;
   rating?: number;
   replied?: boolean;
   hasImage?: boolean;
   from?: string;
-  sort?: "createdAt.desc" | "createdAt.asc" | "rating.asc" | "rating.desc";
+  sort?: ReviewSort;
 }
+
+/** `GET /v1/reviews` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+export const reviewListQuerySchema = z.object({
+  productId: z.string().optional().describe("상품 id 필터"),
+  rating: z.enum(["1", "2", "3", "4", "5"]).optional().describe("별점 필터 (일치)"),
+  replied: z
+    .enum(["true", "false"])
+    .optional()
+    .describe("답글 여부 필터. `true`면 답글 단 리뷰만, `false`면 답글 없는 리뷰만"),
+  hasImage: z.enum(["true", "false"]).optional().describe("`true`면 이미지가 있는 리뷰만"),
+  from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
+  sort: reviewSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
+  ...pageQueryShape(),
+});
+
+/** `POST /v1/reviews/{reviewId}/report` 응답(202) — 신고 접수 */
+export const reviewReportResultSchema = z.object({
+  reviewId: z.string(),
+  status: z.literal("PENDING_REVIEW"),
+});
+
+export type ReviewReportResult = z.infer<typeof reviewReportResultSchema>;

package/src/schemas/order.ts

@@ -209,6 +209,24 @@ export const deliveryInfoSchema = z.object({
 
 export type DeliveryInfo = z.infer<typeof deliveryInfoSchema>;
 
+/** `GET /v1/order-items/{orderItemId}/delivery` 응답 — 배송 정보 + 배송 추적 이벤트 */
+export const deliveryStatusSchema = deliveryInfoSchema.extend({
+  trackingEvents: z
+    .array(z.object({ status: z.string(), location: z.string(), occurredAt: z.string() }))
+    .optional(),
+});
+
+export type DeliveryStatus = z.infer<typeof deliveryStatusSchema>;
+
+/** `PUT /v1/order-items/{orderItemId}/dispatch/tracking` 응답 — 바뀐 송장 */
+export const trackingUpdateResultSchema = z.object({
+  orderItemId: z.string(),
+  carrierCode: z.string(),
+  trackingNumber: z.string(),
+});
+
+export type TrackingUpdateResult = z.infer<typeof trackingUpdateResultSchema>;
+
 export const carrierSchema = z.object({
   carrierCode: z.string(),
   name: z.string(),
@@ -231,3 +249,45 @@ export const cancelBySellerRequestSchema = z.object({
 });
 
 export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
+
+/** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
+export const cancelBySellerResultSchema = z.object({
+  orderItemId: z.string(),
+  refundAmount: z.number().int(),
+  refundedAt: z.string(),
+});
+
+export type CancelBySellerResult = z.infer<typeof cancelBySellerResultSchema>;
+
+/** `PUT /v1/order-items/{orderItemId}/memo` 응답 — 빈 문자열로 저장하면 메모가 지워져 `null`이다 */
+export const orderItemMemoResultSchema = z.object({
+  orderItemId: z.string(),
+  sellerMemo: z.string().nullable(),
+});
+
+export type OrderItemMemoResult = z.infer<typeof orderItemMemoResultSchema>;
+
+/** `POST /v1/order-items/{orderItemId}/purchase-decision/request` 응답 */
+export const purchaseDecisionRequestResultSchema = z.object({
+  orderItemId: z.string(),
+  requestedAt: z.string(),
+});
+
+export type PurchaseDecisionRequestResult = z.infer<typeof purchaseDecisionRequestResultSchema>;
+
+/** `POST /v1/order-items/{orderItemId}/purchase-decision/extend` 응답 — 연장은 최대 2회 */
+export const purchaseDecisionExtendResultSchema = z.object({
+  orderItemId: z.string(),
+  autoDecisionDate: z.string(),
+  extendCount: z.number().int().max(2),
+});
+
+export type PurchaseDecisionExtendResult = z.infer<typeof purchaseDecisionExtendResultSchema>;
+
+/**
+ * `GET /v1/orders/{orderId}/address-change-requests` 응답 — 배송지 변경 요청 플로우는 아직 제공하지 않아
+ * 현재는 항상 빈 배열이다
+ */
+export const addressChangeRequestListSchema = z
+  .array(z.record(z.string(), z.unknown()))
+  .describe("배송지 변경 요청 목록 (현재 항상 빈 배열)");