@sayren/store-sdk 0.5.0 → 0.7.0

package/dist/index.mjs

@@ -150,7 +150,7 @@ function createHttp(options) {
 /**
 * 방문 분석 조회 (관리 API `/v1/analytics/*`, 스코프 `analytics:r`).
 *
-* 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
+* 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
 * 갱신되므로 오늘 값은 `lastComputedAt` 시점까지 반영돼 있다. 봇·자동화 브라우저의 세션은 모든 집계에서 빠진다.
 */
 const reportDate$1 = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "날짜 형식은 YYYY-MM-DD 입니다");
@@ -204,7 +204,8 @@ 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("날짜별 값. 세션이 없는 날은 생략된다")
+	rows: z.array(analyticsTotalsSchema.extend({ date: z.string().describe("일자 (YYYY-MM-DD)") })).describe("날짜별 값. 세션이 없는 날은 생략된다"),
+	excludedBotSessions: z.number().int().describe("집계에서 뺀 봇 세션 수 — 봇 표시 이벤트가 하나라도 있는 세션은 모든 값에서 빠진다")
 });
 const analyticsProductSortSchema = z.enum([
 	"VIEWS",
@@ -227,7 +228,8 @@ const analyticsProductRowSchema = z.object({
 	purchases: z.number().int().describe("이 상품이 포함된 구매(주문) 수"),
 	quantity: z.number().int().describe("구매 수량"),
 	revenue: z.number().int().describe("이 상품의 구매 금액 — 주문 상품 금액(할인 반영, 배송비 제외) 합계. 이후 취소·환불은 빼지 않는다"),
-	purchaseRate: rate("구매율 = 구매 / 조회 세션. 조회 세션이 없으면 null")
+	purchaseRate: rate("구매율 = 구매 / 조회 세션. 조회 세션이 없으면 null"),
+	clickThroughRate: rate("목록 → 상세 전환율 = 상세 조회 / 목록 노출. 노출이 없으면 null(검색·외부 링크로 바로 들어온 조회는 노출 없이 잡힌다)")
 });
 const analyticsProductsSchema = z.object({
 	...rangeMeta,
@@ -275,6 +277,94 @@ const analyticsSourcesSchema = z.object({
 	groupBy: analyticsSourceGroupBySchema,
 	rows: z.array(analyticsSourceRowSchema).describe("세션 수 내림차순")
 });
+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개")
+});
+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("전환율 = 구매 세션 / 세션")
+});
+const analyticsDevicesSchema = z.object({
+	...rangeMeta,
+	rows: z.array(analyticsDeviceRowSchema).describe("기기별 세션 기준 퍼널. 세션 수 내림차순")
+});
+const limitParam = z.coerce.number().int().min(1).max(100).optional().describe("최대 행 수. 기본 20, 최대 100");
+const analyticsPagesQuerySchema = analyticsRangeQuerySchema.extend({ limit: limitParam });
+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("이탈 페이지. 이탈 수 내림차순")
+});
+const analyticsSearchQuerySchema = analyticsRangeQuerySchema.extend({ limit: limitParam });
+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`)에 들지 않는 드문 검색어도 여기 잡힌다")
+});
+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`(아직 진행 중 — 만료 전 대기·승인 중). 실패 분류는 세션의 마지막 결제 시도 기준이다");
+const analyticsCheckoutSchema = z.object({
+	...rangeMeta,
+	sessions: z.number().int().describe("기간 안에 시작한 결제 세션 수(결제 요청 단위)"),
+	outcomes: z.array(z.object({
+		outcome: analyticsCheckoutOutcomeSchema,
+		sessions: z.number().int()
+	})).describe("결과별 결제 세션 수. 결과마다 한 행")
+});
 //#endregion
 //#region src/schemas/api-client.ts
 /**
@@ -654,12 +744,16 @@ const claimSchema = z.object({
 		trackingNumber: z.string().nullable()
 	}).nullable(),
 	requestedAt: z.string(),
-	completedAt: z.string().nullable()
+	completedAt: z.string().nullable(),
+	/** 보류 중이면 자동 해제 시각(ISO 8601), 아니면 null */
+	holdExpiresAt: z.string().nullable(),
+	/** 보류를 이미 썼는지 — 보류는 클레임당 1회라 해제·만료 뒤에도 true */
+	holdUsed: z.boolean()
 });
 /** `GET /v1/claims` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
 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, 포함)"),
@@ -798,7 +892,7 @@ const withdrawCustomerRequestSchema = z.object({
 	]).describe("처리 사유 — 구매자 요청·장기 미이용·부정 이용·기타. 감사 로그에 남는다"),
 	memo: z.string().max(200).optional().describe("사유 보충(선택)")
 });
-/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프론트 탈퇴와 같다) */
 const customerWithdrawalBlockedDetailsSchema = z.object({
 	inProgressOrderItems: z.number().int(),
 	openClaims: z.number().int(),
@@ -816,7 +910,7 @@ const loginProviderSchema = z.enum([
 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(),
@@ -1600,10 +1694,10 @@ 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 */
@@ -1740,8 +1834,8 @@ const variantStockSchema = z.object({
 const productCreateRequestSchema = z.object({
 	name: z.string().min(1).max(100),
 	categoryId: z.string().min(1, "카테고리를 선택해주세요"),
-	salePrice: z.number().int().min(10).multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)"),
-	originalPrice: z.number().int().optional(),
+	salePrice: z.number().int().min(10).multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)").describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
+	originalPrice: z.number().int().optional().describe("정가(할인 전 표시 가격). 원 단위"),
 	description: z.string().optional(),
 	/**
 	* 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -1753,11 +1847,11 @@ const productCreateRequestSchema = 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()
 }).extend(optionModelRequestSchema.shape);
@@ -1873,8 +1967,8 @@ function isWebOrigin(value) {
 		return false;
 	}
 }
-/** 방문 분석을 보낼 수 있는 스토어프런트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
-const analyticsOriginSchema = z.string().trim().max(255).refine(isWebOrigin, "https://shop.example.com 형식(경로 없이)으로 입력해 주세요").describe("스토어프런트 오리진. 예: `https://shop.example.com`");
+/** 방문 분석을 보낼 수 있는 스토어프론트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
+const analyticsOriginSchema = z.string().trim().max(255).refine(isWebOrigin, "https://shop.example.com 형식(경로 없이)으로 입력해 주세요").describe("스토어프론트 오리진. 예: `https://shop.example.com`");
 /** 허용 오리진 상한 */
 const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
 /** `PATCH /v1/store` 본문 — 바꿀 필드만 보낸다 */
@@ -1883,8 +1977,8 @@ const updateStoreRequestSchema = z.object({
 	logoUrl: z.url().optional(),
 	customerCenterPhone: z.string().optional(),
 	businessHours: z.string().max(100).optional(),
-	analyticsAllowedOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프런트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. 넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다"),
-	storefrontOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("스토어프런트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. `analyticsAllowedOrigins`와 같은 목록이다(둘 다 주면 이 값이 이긴다)"),
+	analyticsAllowedOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프론트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. 넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다"),
+	storefrontOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("스토어프론트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. `analyticsAllowedOrigins`와 같은 목록이다(둘 다 주면 이 값이 이긴다)"),
 	guestCheckoutEnabled: z.boolean().optional().describe("비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. 장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다")
 }).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
 const storeSchema = z.object({
@@ -1900,8 +1994,8 @@ const storeSchema = z.object({
 	logoUrl: z.url().nullable(),
 	businessNumber: z.string().nullable(),
 	customerCenterPhone: z.string().nullable(),
-	analyticsAllowedOrigins: z.array(z.string()).describe("방문 분석 수집을 받는 스토어프런트 오리진. 비어 있으면 모든 오리진에서 받는다"),
-	storefrontOrigins: z.array(z.string()).describe("스토어프런트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)"),
+	analyticsAllowedOrigins: z.array(z.string()).describe("방문 분석 수집을 받는 스토어프론트 오리진. 비어 있으면 모든 오리진에서 받는다"),
+	storefrontOrigins: z.array(z.string()).describe("스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)"),
 	guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
 	memberCount: z.number().int(),
 	createdAt: z.string()
@@ -2188,7 +2282,10 @@ function createStoreClient(options) {
 		},
 		carriers: { list: () => storeHttp.request("GET", "/carriers", z.array(carrierSchema)) },
 		claims: {
-			list: (params) => storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: params }),
+			list: (params) => storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: {
+				...params,
+				status: Array.isArray(params?.status) ? params.status.join(",") : params?.status
+			} }),
 			get: (claimId) => storeHttp.request("GET", path`/claims/${claimId}`, claimDetailSchema),
 			approve: (claimId, deductAmount, idempotencyKey) => storeHttp.request("POST", path`/claims/${claimId}/approve`, approveClaimResultSchema, {
 				body: deductAmount !== void 0 ? { deductAmount } : {},
@@ -2202,7 +2299,9 @@ function createStoreClient(options) {
 				trackingNumber
 			} }),
 			hold: (claimId, reason) => storeHttp.request("POST", path`/claims/${claimId}/hold`, claimHoldResultSchema, { body: { reason } }),
-			releaseHold: (claimId) => storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`)
+			releaseHold: (claimId) => storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`),
+			/** 교환 완료 — 재배송 중인 교환을 셀러가 명시적으로 끝낸다 */
+			completeExchange: (claimId) => storeHttp.request("POST", path`/claims/${claimId}/complete-exchange`, claimSchema)
 		},
 		inquiries: {
 			list: (params) => storeHttp.request("GET", "/inquiries", pageSchema(inquirySchema), { query: params }),
@@ -2258,7 +2357,7 @@ function createStoreClient(options) {
 		*/
 get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, { query: salesReportQuerySchema.parse(params) }) },
 		/**
-		* 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+		* 방문 분석 — 스코프 `analytics:r`. 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
 		* 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
 		* 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
 		*/
@@ -2268,7 +2367,17 @@ get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, {
 			/** `GET /v1/analytics/products` — 상품별 노출·조회·장바구니·구매 */
 			products: (params) => storeHttp.request("GET", "/analytics/products", analyticsProductsSchema, { query: analyticsProductsQuerySchema.parse(params) }),
 			/** `GET /v1/analytics/sources` — 채널·소스·캠페인·기기별 세션과 구매 */
-			sources: (params) => storeHttp.request("GET", "/analytics/sources", analyticsSourcesSchema, { query: analyticsSourcesQuerySchema.parse(params) })
+			sources: (params) => storeHttp.request("GET", "/analytics/sources", analyticsSourcesSchema, { query: analyticsSourcesQuerySchema.parse(params) }),
+			/** `GET /v1/analytics/realtime` — 최근 5분 방문자·세션·페이지(원본 이벤트 기준, 봇 제외) */
+			realtime: () => storeHttp.request("GET", "/analytics/realtime", analyticsRealtimeSchema),
+			/** `GET /v1/analytics/devices` — 기기별 세션 퍼널 */
+			devices: (params) => storeHttp.request("GET", "/analytics/devices", analyticsDevicesSchema, { query: analyticsRangeQuerySchema.parse(params) }),
+			/** `GET /v1/analytics/pages` — 첫 페이지(진입·반송)와 이탈 페이지 */
+			pages: (params) => storeHttp.request("GET", "/analytics/pages", analyticsPagesSchema, { query: analyticsPagesQuerySchema.parse(params) }),
+			/** `GET /v1/analytics/search` — 검색어별 검색·결과 0개·검색 후 구매 */
+			search: (params) => storeHttp.request("GET", "/analytics/search", analyticsSearchSchema, { query: analyticsSearchQuerySchema.parse(params) }),
+			/** `GET /v1/analytics/checkout` — 결제 세션의 결과별 수(결제 단계 이탈 이유) */
+			checkout: (params) => storeHttp.request("GET", "/analytics/checkout", analyticsCheckoutSchema, { query: analyticsRangeQuerySchema.parse(params) })
 		},
 		/**
 		* 결제 내역 — 스코프 `settlement:r`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
@@ -2414,7 +2523,7 @@ get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, {
 			get: () => storeHttp.request("GET", "/store", storeSchema),
 			/**
 			* `PATCH /v1/store` — 스코프 `store:rw`. 바꿀 필드만 보낸다. `analyticsAllowedOrigins`는 방문 분석 수집을 받을
-			* 스토어프런트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
+			* 스토어프론트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
 			*/
 			update: (body) => storeHttp.request("PATCH", "/store", storeSchema, { body: updateStoreRequestSchema.parse(body) }),
 			listMembers: () => storeHttp.request("GET", "/store/members", z.array(storeMemberSchema)),
@@ -2803,4 +2912,4 @@ function createStoreSession(options) {
 	};
 }
 //#endregion
-export { ApiError, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_OPTION_GROUPS, MAX_VALUES_PER_GROUP, MAX_VARIANTS, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, RESERVED_STORE_CODES, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressChangeRequestListSchema, addressTypeSchema, analyticsChannelSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approveClaimResultSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, createPkcePair, createStoreClient, createStoreSession, customerAddressSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, effectivePaymentRoutingModeSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationListQuerySchema, invitationSchema, isReservedStoreCode, isStoreScope, isWebOrigin, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentRoutingModeSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageUploadResultSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, refreshUserToken, rejectClaimRequestSchema, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingUpdateResultSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema };
+export { ApiError, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_OPTION_GROUPS, MAX_VALUES_PER_GROUP, MAX_VARIANTS, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, RESERVED_STORE_CODES, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressChangeRequestListSchema, addressTypeSchema, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approveClaimResultSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, createPkcePair, createStoreClient, createStoreSession, customerAddressSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, effectivePaymentRoutingModeSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationListQuerySchema, invitationSchema, isReservedStoreCode, isStoreScope, isWebOrigin, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentRoutingModeSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageUploadResultSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, refreshUserToken, rejectClaimRequestSchema, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingUpdateResultSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema };

package/dist/server.d.mts

@@ -1,4 +1,48 @@
 import { a as WEBHOOK_HEADERS, i as WEBHOOK_EVENT_TYPE_HEADER, n as WEBHOOK_DELIVERY_ID_HEADER, o as WEBHOOK_SIGNATURE_HEADER, r as WEBHOOK_EVENT_ID_HEADER, s as WEBHOOK_USER_AGENT, t as WEBHOOK_DEFAULT_TOLERANCE_SEC } from "./webhook-headers-D6QmPdEJ.mjs";
+//#region src/member-delegation.d.ts
+/**
+ * 구매자 위임 — 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰으로 바꾼다
+ * (token-exchange의 `member-uid`·`member-ref` 확장, auth-spec §12-10). 클라이언트 시크릿을 쓰므로 **서버에서만** 부른다.
+ *
+ * 스토어에 바인딩된 confidential 클라이언트 + `member:delegate` 스코프가 필요하다. 응답은 구매자 액세스 토큰(30분)이고
+ * refresh는 없다 — 만료되면 같은 호출로 다시 받는다.
+ */
+interface DelegatedMemberToken {
+  accessToken: string;
+  expiresIn: number;
+  memberId: string;
+}
+interface DelegationOptions {
+  /** api 주소(예: `https://api.sayren.app`) — `/v1/oauth2/token`을 붙인다 */
+  baseUrl: string;
+  clientId: string;
+  clientSecret: string;
+  fetch?: typeof globalThis.fetch;
+}
+/** 셀러 자체 인증의 사용자 id로 지목한다. 처음 보는 id면 구매자를 만든다(이메일·이름은 그때만 쓴다) */
+export declare function delegateMemberByUid(options: DelegationOptions & {
+  uid: string;
+  email?: string;
+  name?: string;
+  /**
+   * 사용자가 내 서비스에서 실제로 로그인한 시각. 주면 구매자 토큰의 인증 시각이 되고(탈퇴처럼 최근 인증이 필요한 동작에
+   * 쓴다), 주지 않으면 인증 시각이 없는 토큰이 나온다
+   */
+  authenticatedAt?: Date;
+}): Promise<DelegatedMemberToken>;
+/** 이메일로 지목한다. 처음 보는 이메일이면 구매자를 만든다 */
+export declare function delegateMemberByEmail(options: DelegationOptions & {
+  email: string;
+  name?: string;
+}): Promise<DelegatedMemberToken>;
+/** 위임 실패 — `error`는 OAuth 오류 코드(`invalid_client`·`invalid_scope`·`invalid_request` 등) */
+export declare class MemberDelegationError extends Error {
+  readonly error: string;
+  readonly description: string;
+  readonly status: number;
+  constructor(error: string, description: string, status: number);
+}
+//#endregion
 //#region src/webhook-signature.d.ts
 interface SignWebhookPayloadOptions {
   /** 요청 본문 원문. 전송하는 바이트와 정확히 같아야 한다 */
@@ -56,4 +100,4 @@ interface VerifyWebhookSignatureOptions {
  */
 export declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<WebhookSignatureVerification>;
 //#endregion
-export { type ParsedWebhookSignature, type SignWebhookPayloadOptions, type VerifyWebhookSignatureOptions, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, type WebhookSignatureFailureReason, type WebhookSignatureVerification };
+export { type DelegatedMemberToken, type ParsedWebhookSignature, type SignWebhookPayloadOptions, type VerifyWebhookSignatureOptions, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, type WebhookSignatureFailureReason, type WebhookSignatureVerification };

package/dist/server.mjs

@@ -1,4 +1,59 @@
 import { a as WEBHOOK_HEADERS, i as WEBHOOK_EVENT_TYPE_HEADER, n as WEBHOOK_DELIVERY_ID_HEADER, o as WEBHOOK_SIGNATURE_HEADER, r as WEBHOOK_EVENT_ID_HEADER, s as WEBHOOK_USER_AGENT, t as WEBHOOK_DEFAULT_TOLERANCE_SEC } from "./webhook-headers-ap_exsb9.mjs";
+//#region src/member-delegation.ts
+/** 셀러 자체 인증의 사용자 id로 지목한다. 처음 보는 id면 구매자를 만든다(이메일·이름은 그때만 쓴다) */
+function delegateMemberByUid(options) {
+	return delegate(options, {
+		subject_token_type: "urn:sayren:params:oauth:token-type:member-uid",
+		subject_token: options.uid,
+		...options.authenticatedAt ? { subject_auth_time: String(Math.floor(options.authenticatedAt.getTime() / 1e3)) } : {},
+		...options.email ? { subject_email: options.email } : {},
+		...options.name ? { subject_name: options.name } : {}
+	});
+}
+/** 이메일로 지목한다. 처음 보는 이메일이면 구매자를 만든다 */
+function delegateMemberByEmail(options) {
+	return delegate(options, {
+		subject_token_type: "urn:sayren:params:oauth:token-type:member-ref",
+		subject_token: options.email,
+		...options.name ? { subject_name: options.name } : {}
+	});
+}
+async function delegate(options, subject) {
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const basic = btoa(`${options.clientId}:${options.clientSecret}`);
+	const res = await doFetch(`${options.baseUrl.replace(/\/+$/, "")}/v1/oauth2/token`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/x-www-form-urlencoded",
+			authorization: `Basic ${basic}`
+		},
+		body: new URLSearchParams({
+			grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+			...subject
+		}).toString()
+	});
+	const body = await res.json().catch(() => ({}));
+	if (!res.ok || typeof body.access_token !== "string") throw new MemberDelegationError(typeof body.error === "string" ? body.error : `http_${res.status}`, typeof body.error_description === "string" ? body.error_description : "", res.status);
+	return {
+		accessToken: body.access_token,
+		expiresIn: Number(body.expires_in),
+		memberId: String(body.memberId)
+	};
+}
+/** 위임 실패 — `error`는 OAuth 오류 코드(`invalid_client`·`invalid_scope`·`invalid_request` 등) */
+var MemberDelegationError = class extends Error {
+	error;
+	description;
+	status;
+	constructor(error, description, status) {
+		super(description ? `${error}: ${description}` : error);
+		this.error = error;
+		this.description = description;
+		this.status = status;
+		this.name = "MemberDelegationError";
+	}
+};
+//#endregion
 //#region src/webhook-signature.ts
 /**
 * 웹훅 서명 (`Sayren-Signature`) 생성·파싱·검증.
@@ -122,4 +177,4 @@ async function verifyWebhookSignature(options) {
 	};
 }
 //#endregion
-export { WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, parseWebhookSignatureHeader, signWebhookPayload, verifyWebhookSignature };
+export { MemberDelegationError, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, delegateMemberByEmail, delegateMemberByUid, parseWebhookSignatureHeader, signWebhookPayload, verifyWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -2,13 +2,22 @@ import { z } from "zod";
 import { base64Utf8 } from "./base64";
 import { createHttp, path, type Query, resolveToken, type TokenSource, unwrapData } from "./http";
 import {
+  type AnalyticsPagesParams,
   type AnalyticsProductsParams,
   type AnalyticsRangeParams,
+  type AnalyticsSearchParams,
   type AnalyticsSourcesParams,
+  analyticsCheckoutSchema,
+  analyticsDevicesSchema,
   analyticsOverviewSchema,
+  analyticsPagesQuerySchema,
+  analyticsPagesSchema,
   analyticsProductsQuerySchema,
   analyticsProductsSchema,
   analyticsRangeQuerySchema,
+  analyticsRealtimeSchema,
+  analyticsSearchQuerySchema,
+  analyticsSearchSchema,
   analyticsSourcesQuerySchema,
   analyticsSourcesSchema,
 } from "./schemas/analytics";
@@ -533,7 +542,12 @@ export function createStoreClient(options: StoreClientOptions) {
 
     claims: {
       list: (params?: ClaimListParams) =>
-        storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: params as Query }),
+        storeHttp.request("GET", "/claims", pageSchema(claimSchema), {
+          query: {
+            ...params,
+            status: Array.isArray(params?.status) ? params.status.join(",") : params?.status,
+          } as Query,
+        }),
       get: (claimId: string) =>
         storeHttp.request("GET", path`/claims/${claimId}`, claimDetailSchema),
       approve: (claimId: string, deductAmount?: number, idempotencyKey?: string) =>
@@ -561,6 +575,9 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       releaseHold: (claimId: string) =>
         storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`),
+      /** 교환 완료 — 재배송 중인 교환을 셀러가 명시적으로 끝낸다 */
+      completeExchange: (claimId: string) =>
+        storeHttp.request("POST", path`/claims/${claimId}/complete-exchange`, claimSchema),
     },
 
     inquiries: {
@@ -691,7 +708,7 @@ export function createStoreClient(options: StoreClientOptions) {
     },
 
     /**
-     * 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+     * 방문 분석 — 스코프 `analytics:r`. 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
      * 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
      * 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
      */
@@ -711,6 +728,28 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("GET", "/analytics/sources", analyticsSourcesSchema, {
           query: analyticsSourcesQuerySchema.parse(params),
         }),
+      /** `GET /v1/analytics/realtime` — 최근 5분 방문자·세션·페이지(원본 이벤트 기준, 봇 제외) */
+      realtime: () => storeHttp.request("GET", "/analytics/realtime", analyticsRealtimeSchema),
+      /** `GET /v1/analytics/devices` — 기기별 세션 퍼널 */
+      devices: (params: AnalyticsRangeParams) =>
+        storeHttp.request("GET", "/analytics/devices", analyticsDevicesSchema, {
+          query: analyticsRangeQuerySchema.parse(params),
+        }),
+      /** `GET /v1/analytics/pages` — 첫 페이지(진입·반송)와 이탈 페이지 */
+      pages: (params: AnalyticsPagesParams) =>
+        storeHttp.request("GET", "/analytics/pages", analyticsPagesSchema, {
+          query: analyticsPagesQuerySchema.parse(params) as unknown as Query,
+        }),
+      /** `GET /v1/analytics/search` — 검색어별 검색·결과 0개·검색 후 구매 */
+      search: (params: AnalyticsSearchParams) =>
+        storeHttp.request("GET", "/analytics/search", analyticsSearchSchema, {
+          query: analyticsSearchQuerySchema.parse(params) as unknown as Query,
+        }),
+      /** `GET /v1/analytics/checkout` — 결제 세션의 결과별 수(결제 단계 이탈 이유) */
+      checkout: (params: AnalyticsRangeParams) =>
+        storeHttp.request("GET", "/analytics/checkout", analyticsCheckoutSchema, {
+          query: analyticsRangeQuerySchema.parse(params),
+        }),
     },
 
     /**
@@ -944,7 +983,7 @@ export function createStoreClient(options: StoreClientOptions) {
       get: () => storeHttp.request("GET", "/store", storeSchema),
       /**
        * `PATCH /v1/store` — 스코프 `store:rw`. 바꿀 필드만 보낸다. `analyticsAllowedOrigins`는 방문 분석 수집을 받을
-       * 스토어프런트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
+       * 스토어프론트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
        */
       update: (body: UpdateStoreRequest) =>
         storeHttp.request("PATCH", "/store", storeSchema, {

package/src/member-delegation.ts

@@ -0,0 +1,98 @@
+/**
+ * 구매자 위임 — 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰으로 바꾼다
+ * (token-exchange의 `member-uid`·`member-ref` 확장, auth-spec §12-10). 클라이언트 시크릿을 쓰므로 **서버에서만** 부른다.
+ *
+ * 스토어에 바인딩된 confidential 클라이언트 + `member:delegate` 스코프가 필요하다. 응답은 구매자 액세스 토큰(30분)이고
+ * refresh는 없다 — 만료되면 같은 호출로 다시 받는다.
+ */
+
+export interface DelegatedMemberToken {
+  accessToken: string;
+  expiresIn: number;
+  memberId: string;
+}
+
+interface DelegationOptions {
+  /** api 주소(예: `https://api.sayren.app`) — `/v1/oauth2/token`을 붙인다 */
+  baseUrl: string;
+  clientId: string;
+  clientSecret: string;
+  fetch?: typeof globalThis.fetch;
+}
+
+/** 셀러 자체 인증의 사용자 id로 지목한다. 처음 보는 id면 구매자를 만든다(이메일·이름은 그때만 쓴다) */
+export function delegateMemberByUid(
+  options: DelegationOptions & {
+    uid: string;
+    email?: string;
+    name?: string;
+    /**
+     * 사용자가 내 서비스에서 실제로 로그인한 시각. 주면 구매자 토큰의 인증 시각이 되고(탈퇴처럼 최근 인증이 필요한 동작에
+     * 쓴다), 주지 않으면 인증 시각이 없는 토큰이 나온다
+     */
+    authenticatedAt?: Date;
+  },
+): Promise<DelegatedMemberToken> {
+  return delegate(options, {
+    subject_token_type: "urn:sayren:params:oauth:token-type:member-uid",
+    subject_token: options.uid,
+    ...(options.authenticatedAt
+      ? { subject_auth_time: String(Math.floor(options.authenticatedAt.getTime() / 1000)) }
+      : {}),
+    ...(options.email ? { subject_email: options.email } : {}),
+    ...(options.name ? { subject_name: options.name } : {}),
+  });
+}
+
+/** 이메일로 지목한다. 처음 보는 이메일이면 구매자를 만든다 */
+export function delegateMemberByEmail(
+  options: DelegationOptions & { email: string; name?: string },
+): Promise<DelegatedMemberToken> {
+  return delegate(options, {
+    subject_token_type: "urn:sayren:params:oauth:token-type:member-ref",
+    subject_token: options.email,
+    ...(options.name ? { subject_name: options.name } : {}),
+  });
+}
+
+async function delegate(
+  options: DelegationOptions,
+  subject: Record<string, string>,
+): Promise<DelegatedMemberToken> {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const basic = btoa(`${options.clientId}:${options.clientSecret}`);
+  const res = await doFetch(`${options.baseUrl.replace(/\/+$/, "")}/v1/oauth2/token`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      authorization: `Basic ${basic}`,
+    },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+      ...subject,
+    }).toString(),
+  });
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  if (!res.ok || typeof body.access_token !== "string") {
+    const error = typeof body.error === "string" ? body.error : `http_${res.status}`;
+    const description = typeof body.error_description === "string" ? body.error_description : "";
+    throw new MemberDelegationError(error, description, res.status);
+  }
+  return {
+    accessToken: body.access_token,
+    expiresIn: Number(body.expires_in),
+    memberId: String(body.memberId),
+  };
+}
+
+/** 위임 실패 — `error`는 OAuth 오류 코드(`invalid_client`·`invalid_scope`·`invalid_request` 등) */
+export class MemberDelegationError extends Error {
+  constructor(
+    readonly error: string,
+    readonly description: string,
+    readonly status: number,
+  ) {
+    super(description ? `${error}: ${description}` : error);
+    this.name = "MemberDelegationError";
+  }
+}