@sayren/store-sdk 0.5.0 → 0.7.0

package/src/schemas/analytics.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 /**
  * 방문 분석 조회 (관리 API `/v1/analytics/*`, 스코프 `analytics:r`).
  *
- * 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
+ * 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
  * 갱신되므로 오늘 값은 `lastComputedAt` 시점까지 반영돼 있다. 봇·자동화 브라우저의 세션은 모든 집계에서 빠진다.
  */
 
@@ -96,6 +96,10 @@ export const analyticsOverviewSchema = z.object({
   rows: z
     .array(analyticsTotalsSchema.extend({ date: z.string().describe("일자 (YYYY-MM-DD)") }))
     .describe("날짜별 값. 세션이 없는 날은 생략된다"),
+  excludedBotSessions: z
+    .number()
+    .int()
+    .describe("집계에서 뺀 봇 세션 수 — 봇 표시 이벤트가 하나라도 있는 세션은 모든 값에서 빠진다"),
 });
 export type AnalyticsOverview = z.infer<typeof analyticsOverviewSchema>;
 
@@ -132,6 +136,9 @@ export const analyticsProductRowSchema = z.object({
       "이 상품의 구매 금액 — 주문 상품 금액(할인 반영, 배송비 제외) 합계. 이후 취소·환불은 빼지 않는다",
     ),
   purchaseRate: rate("구매율 = 구매 / 조회 세션. 조회 세션이 없으면 null"),
+  clickThroughRate: rate(
+    "목록 → 상세 전환율 = 상세 조회 / 목록 노출. 노출이 없으면 null(검색·외부 링크로 바로 들어온 조회는 노출 없이 잡힌다)",
+  ),
 });
 export type AnalyticsProductRow = z.infer<typeof analyticsProductRowSchema>;
 
@@ -198,3 +205,141 @@ export const analyticsSourcesSchema = z.object({
   rows: z.array(analyticsSourceRowSchema).describe("세션 수 내림차순"),
 });
 export type AnalyticsSources = z.infer<typeof analyticsSourcesSchema>;
+
+// ─── 2차(#6): 실시간·기기별 퍼널·첫/이탈 페이지·검색어·결제 단계 이탈 ─────────────────────
+
+export const analyticsRealtimeSchema = z.object({
+  asOf: z.string().describe("기준 시각(ISO 8601)"),
+  windowMinutes: z.literal(5).describe("최근 몇 분 동안 활동한 방문을 세는가"),
+  visitors: z.number().int().describe("최근 5분 안에 이벤트가 있는 방문자 수(봇 제외)"),
+  sessions: z.number().int(),
+  pageViews: z.number().int(),
+  pages: z
+    .array(z.object({ path: z.string(), visitors: z.number().int(), pageViews: z.number().int() }))
+    .describe("최근 5분 페이지뷰가 있는 경로. 방문자 수 내림차순 최대 10개"),
+});
+export type AnalyticsRealtime = z.infer<typeof analyticsRealtimeSchema>;
+
+export const analyticsDeviceRowSchema = z.object({
+  device: z.enum(["desktop", "mobile", "tablet", "unknown"]),
+  sessions: z.number().int(),
+  productViewSessions: z.number().int(),
+  addToCartSessions: z.number().int(),
+  beginCheckoutSessions: z.number().int(),
+  purchaseSessions: z.number().int(),
+  conversionRate: rate("전환율 = 구매 세션 / 세션"),
+});
+export type AnalyticsDeviceRow = z.infer<typeof analyticsDeviceRowSchema>;
+
+export const analyticsDevicesSchema = z.object({
+  ...rangeMeta,
+  rows: z.array(analyticsDeviceRowSchema).describe("기기별 세션 기준 퍼널. 세션 수 내림차순"),
+});
+export type AnalyticsDevices = z.infer<typeof analyticsDevicesSchema>;
+
+const limitParam = z.coerce
+  .number()
+  .int()
+  .min(1)
+  .max(100)
+  .optional()
+  .describe("최대 행 수. 기본 20, 최대 100");
+
+export const analyticsPagesQuerySchema = analyticsRangeQuerySchema.extend({ limit: limitParam });
+export type AnalyticsPagesParams = z.infer<typeof analyticsPagesQuerySchema>;
+
+export const analyticsPagesSchema = z.object({
+  ...rangeMeta,
+  landings: z
+    .array(
+      z.object({
+        path: z.string(),
+        entrances: z.number().int().describe("이 페이지로 시작한 세션 수"),
+        bounces: z.number().int().describe("이 페이지로 시작해 참여하지 않고 끝난 세션 수"),
+        bounceRate: rate("반송률 = 반송 / 진입"),
+      }),
+    )
+    .describe("첫 페이지. 진입 수 내림차순"),
+  exits: z
+    .array(
+      z.object({
+        path: z.string(),
+        pageViews: z.number().int(),
+        exits: z.number().int().describe("이 페이지가 세션의 마지막 페이지뷰였던 수"),
+        exitRate: rate("이탈률 = 이탈 / 페이지뷰"),
+      }),
+    )
+    .describe("이탈 페이지. 이탈 수 내림차순"),
+});
+export type AnalyticsPages = z.infer<typeof analyticsPagesSchema>;
+
+export const analyticsSearchQuerySchema = analyticsRangeQuerySchema.extend({ limit: limitParam });
+export type AnalyticsSearchParams = z.infer<typeof analyticsSearchQuerySchema>;
+
+export const analyticsSearchSchema = z.object({
+  ...rangeMeta,
+  summary: z.object({
+    searches: z.number().int(),
+    zeroResultSearches: z.number().int().describe("결과가 0개였던 검색 수"),
+    searchSessions: z.number().int().describe("검색한 세션 수(세션당 한 번)"),
+    purchaseSessions: z
+      .number()
+      .int()
+      .describe(
+        "검색한 뒤 같은 날 구매한 세션 수(세션당 한 번). 검색 전에 끝난 구매는 세지 않는다",
+      ),
+    conversionRate: rate("검색 후 구매율 = 구매 세션 / 검색 세션"),
+  }),
+  terms: z
+    .array(
+      z.object({
+        term: z.string().describe("검색어 — 소문자, 공백 정리"),
+        searches: z.number().int(),
+        zeroResultSearches: z.number().int(),
+        searchSessions: z.number().int().describe("이 검색어로 검색한 세션 수"),
+        purchaseSessions: z.number().int().describe("이 검색어로 검색한 뒤 같은 날 구매한 세션 수"),
+        conversionRate: rate("검색 후 구매율 = 구매 세션 / 검색 세션"),
+      }),
+    )
+    .describe(
+      "검색 수 내림차순. 세션 수는 검색어마다 세므로 여러 검색어를 쓴 세션은 검색어마다 잡힌다(더하면 요약보다 크다)",
+    ),
+  zeroResultTerms: z
+    .array(
+      z.object({
+        term: z.string(),
+        searches: z.number().int(),
+        zeroResultSearches: z.number().int(),
+      }),
+    )
+    .describe(
+      "결과가 0개였던 적이 있는 검색어. 결과 없음 수 내림차순 — 검색 수 상위(`terms`)에 들지 않는 드문 검색어도 여기 잡힌다",
+    ),
+});
+export type AnalyticsSearch = z.infer<typeof analyticsSearchSchema>;
+
+export const analyticsCheckoutOutcomeSchema = z
+  .enum([
+    "COMPLETED",
+    "NOT_OPENED",
+    "USER_CANCELED",
+    "DECLINED",
+    "PREPARE_FAILURE",
+    "OTHER",
+    "IN_PROGRESS",
+  ])
+  .describe(
+    "결제 세션의 최종 결과 — `COMPLETED`(결제 완료), `NOT_OPENED`(결제창을 열지 않고 끝남), `USER_CANCELED`(결제창에서 취소), " +
+      "`DECLINED`(카드 거절 등 승인 거절), `PREPARE_FAILURE`(결제창을 띄우기 전 장애), `OTHER`(그 밖의 이탈·만료), " +
+      "`IN_PROGRESS`(아직 진행 중 — 만료 전 대기·승인 중). 실패 분류는 세션의 마지막 결제 시도 기준이다",
+  );
+export type AnalyticsCheckoutOutcome = z.infer<typeof analyticsCheckoutOutcomeSchema>;
+
+export const analyticsCheckoutSchema = z.object({
+  ...rangeMeta,
+  sessions: z.number().int().describe("기간 안에 시작한 결제 세션 수(결제 요청 단위)"),
+  outcomes: z
+    .array(z.object({ outcome: analyticsCheckoutOutcomeSchema, sessions: z.number().int() }))
+    .describe("결과별 결제 세션 수. 결과마다 한 행"),
+});
+export type AnalyticsCheckout = z.infer<typeof analyticsCheckoutSchema>;

package/src/schemas/claim.ts

@@ -53,13 +53,18 @@ export const claimSchema = z.object({
     .nullable(),
   requestedAt: z.string(),
   completedAt: z.string().nullable(),
+  /** 보류 중이면 자동 해제 시각(ISO 8601), 아니면 null */
+  holdExpiresAt: z.string().nullable(),
+  /** 보류를 이미 썼는지 — 보류는 클레임당 1회라 해제·만료 뒤에도 true */
+  holdUsed: z.boolean(),
 });
 
 export type Claim = z.infer<typeof claimSchema>;
 
 export interface ClaimListParams extends PageParams {
   type?: ClaimType;
-  status?: ClaimStatus;
+  /** 여러 상태를 한 번에 거를 수 있다(처리 대기 목록 등) */
+  status?: ClaimStatus | ClaimStatus[];
   orderItemId?: string;
   requestedFrom?: string;
   requestedTo?: string;
@@ -68,7 +73,10 @@ export interface ClaimListParams extends PageParams {
 /** `GET /v1/claims` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
 export const claimListQuerySchema = z.object({
   type: claimTypeSchema.optional().describe("클레임 유형 필터"),
-  status: claimStatusSchema.optional().describe("클레임 상태 필터"),
+  status: z
+    .string()
+    .optional()
+    .describe("클레임 상태 필터. 쉼표로 여러 개를 줄 수 있다 (예: `REQUESTED,HELD,COLLECTED`)"),
   orderItemId: z.string().optional().describe("주문상품 id 필터"),
   requestedFrom: z.string().optional().describe("요청 시각 조회 시작 (ISO 8601, 포함)"),
   requestedTo: z.string().optional().describe("요청 시각 조회 끝 (ISO 8601, 포함)"),

package/src/schemas/customer.ts

@@ -115,7 +115,7 @@ export const withdrawCustomerRequestSchema = z.object({
 });
 export type WithdrawCustomerRequest = z.infer<typeof withdrawCustomerRequestSchema>;
 
-/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프론트 탈퇴와 같다) */
 export const customerWithdrawalBlockedDetailsSchema = z.object({
   inProgressOrderItems: z.number().int(),
   openClaims: z.number().int(),

package/src/schemas/login.ts

@@ -8,7 +8,7 @@ export type LoginProvider = z.infer<typeof loginProviderSchema>;
 export const loginProviderStatusSchema = z.object({
   provider: loginProviderSchema,
   connected: z.boolean(),
-  /** 스토어프런트에서 사용 중인지. 연결 안 됐으면 false */
+  /** 스토어프론트에서 사용 중인지. 연결 안 됐으면 false */
   enabled: z.boolean(),
   clientIdPrefix: z.string().nullable().describe("클라이언트 ID(카카오 REST API 키) 앞 4자리"),
   secretPrefix: z.string().nullable(),

package/src/schemas/product.ts

@@ -13,10 +13,14 @@ export const productSummarySchema = z.object({
   productId: z.string(),
   name: z.string(),
   status: productStatusSchema,
-  salePrice: z.number().int(),
-  discountedPrice: z.number().int().nullable(),
+  salePrice: z.number().int().describe("판매가. 원(KRW) 단위 정수"),
+  discountedPrice: z
+    .number()
+    .int()
+    .nullable()
+    .describe("즉시 할인 적용가. 원 단위. 할인이 없으면 null"),
   /** usable variant 재고 합계 (서버 계산) */
-  stockQuantity: z.number().int(),
+  stockQuantity: z.number().int().describe("판매 가능한 옵션 재고의 합계. 서버가 계산한다"),
   categoryId: z.string().nullable(),
   thumbnailUrl: z.url().optional(),
   /** optionGroups.length > 0 */
@@ -199,8 +203,9 @@ export const productCreateRequestSchema = z
       .number()
       .int()
       .min(10)
-      .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)"),
-    originalPrice: z.number().int().optional(),
+      .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)")
+      .describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
+    originalPrice: z.number().int().optional().describe("정가(할인 전 표시 가격). 원 단위"),
     description: z.string().optional(),
     /**
      * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -209,11 +214,17 @@ export const productCreateRequestSchema = z
     descriptionJson: z.string().nullable().optional(),
     images: z.array(z.url()).min(1).max(10).optional(),
     attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
-    deliveryType: deliveryTypeSchema.default("PAID"),
-    deliveryFee: z.number().int().default(0),
-    conditionalFreeAmount: z.number().int().optional(),
-    returnFee: z.number().int().default(0),
-    exchangeFee: z.number().int().default(0),
+    deliveryType: deliveryTypeSchema
+      .default("PAID")
+      .describe("배송비 유형. FREE 무료, PAID 유료, CONDITIONAL_FREE 조건부 무료"),
+    deliveryFee: z.number().int().default(0).describe("배송비. 원 단위"),
+    conditionalFreeAmount: z
+      .number()
+      .int()
+      .optional()
+      .describe("CONDITIONAL_FREE일 때 무료 배송이 되는 주문 금액. 원 단위"),
+    returnFee: z.number().int().default(0).describe("반품 배송비. 원 단위"),
+    exchangeFee: z.number().int().default(0).describe("교환 배송비. 원 단위"),
     shippingAddressId: z.string().optional(),
     returnAddressId: z.string().optional(),
   })

package/src/schemas/store.ts

@@ -91,13 +91,13 @@ export function isWebOrigin(value: string): boolean {
   }
 }
 
-/** 방문 분석을 보낼 수 있는 스토어프런트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
+/** 방문 분석을 보낼 수 있는 스토어프론트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
 export const analyticsOriginSchema = z
   .string()
   .trim()
   .max(255)
   .refine(isWebOrigin, "https://shop.example.com 형식(경로 없이)으로 입력해 주세요")
-  .describe("스토어프런트 오리진. 예: `https://shop.example.com`");
+  .describe("스토어프론트 오리진. 예: `https://shop.example.com`");
 
 /** 허용 오리진 상한 */
 export const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
@@ -114,7 +114,7 @@ export const updateStoreRequestSchema = z
       .max(MAX_ANALYTICS_ALLOWED_ORIGINS)
       .optional()
       .describe(
-        "@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프런트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. " +
+        "@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프론트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. " +
           "넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다",
       ),
     storefrontOrigins: z
@@ -122,7 +122,7 @@ export const updateStoreRequestSchema = z
       .max(MAX_ANALYTICS_ALLOWED_ORIGINS)
       .optional()
       .describe(
-        "스토어프런트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. " +
+        "스토어프론트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. " +
           "`analyticsAllowedOrigins`와 같은 목록이다(둘 다 주면 이 값이 이긴다)",
       ),
     guestCheckoutEnabled: z
@@ -149,11 +149,11 @@ export const storeSchema = z.object({
   customerCenterPhone: z.string().nullable(),
   analyticsAllowedOrigins: z
     .array(z.string())
-    .describe("방문 분석 수집을 받는 스토어프런트 오리진. 비어 있으면 모든 오리진에서 받는다"),
+    .describe("방문 분석 수집을 받는 스토어프론트 오리진. 비어 있으면 모든 오리진에서 받는다"),
   storefrontOrigins: z
     .array(z.string())
     .describe(
-      "스토어프런트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)",
+      "스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)",
     ),
   guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
   memberCount: z.number().int(),

package/src/server.ts

@@ -3,6 +3,12 @@
  * 브라우저 번들에서 import하지 않는다.
  */
 
+export {
+  type DelegatedMemberToken,
+  delegateMemberByEmail,
+  delegateMemberByUid,
+  MemberDelegationError,
+} from "./member-delegation";
 export {
   WEBHOOK_DEFAULT_TOLERANCE_SEC,
   WEBHOOK_DELIVERY_ID_HEADER,