@sayren/store-sdk 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -146,6 +146,136 @@ function createHttp(options) {
 	};
 }
 //#endregion
+//#region src/schemas/analytics.ts
+/**
+* 방문 분석 조회 (관리 API `/v1/analytics/*`, 스코프 `analytics:r`).
+*
+* 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
+* 갱신되므로 오늘 값은 `lastComputedAt` 시점까지 반영돼 있다. 봇·자동화 브라우저의 세션은 모든 집계에서 빠진다.
+*/
+const reportDate$1 = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "날짜 형식은 YYYY-MM-DD 입니다");
+const includeTest = z.enum(["true", "false"]).optional().describe("테스트 결제(샌드박스 결제)로 만든 구매 포함 여부. 기본 `false`");
+const analyticsRangeQuerySchema = z.object({
+	from: reportDate$1.describe("시작일 (YYYY-MM-DD, Asia/Seoul 기준, 포함)"),
+	to: reportDate$1.describe("종료일 (YYYY-MM-DD, 포함). from부터 최대 92일"),
+	includeTest
+});
+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) => z.number().min(0).nullable().describe(description);
+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")
+});
+const analyticsFunnelStepSchema = z.object({
+	step: z.enum([
+		"SESSION",
+		"PRODUCT_VIEW",
+		"ADD_TO_CART",
+		"BEGIN_CHECKOUT",
+		"PURCHASE"
+	]),
+	sessions: z.number().int(),
+	rateFromPrevious: rate("직전 단계 대비 비율. 첫 단계이거나 직전 단계가 0이면 null")
+});
+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("날짜별 값. 세션이 없는 날은 생략된다")
+});
+const analyticsProductSortSchema = z.enum([
+	"VIEWS",
+	"ADD_TO_CARTS",
+	"PURCHASES",
+	"REVENUE",
+	"IMPRESSIONS"
+]).describe("정렬 기준(내림차순). 기본 `VIEWS`");
+const analyticsProductsQuerySchema = analyticsRangeQuerySchema.extend({
+	sort: analyticsProductSortSchema.optional(),
+	limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 행 수. 기본 20, 최대 100")
+});
+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")
+});
+const analyticsProductsSchema = z.object({
+	...rangeMeta,
+	sort: analyticsProductSortSchema,
+	rows: z.array(analyticsProductRowSchema)
+});
+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`(페이지뷰 없이 서버 이벤트만 있는 세션)");
+const analyticsSourceGroupBySchema = z.enum([
+	"CHANNEL",
+	"SOURCE",
+	"CAMPAIGN",
+	"DEVICE"
+]).describe("행 집계 기준. 기본 `CHANNEL`");
+const analyticsSourcesQuerySchema = analyticsRangeQuerySchema.extend({ groupBy: analyticsSourceGroupBySchema.optional() });
+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("전환율 = 구매 세션 / 세션")
+});
+const analyticsSourcesSchema = z.object({
+	...rangeMeta,
+	groupBy: analyticsSourceGroupBySchema,
+	rows: z.array(analyticsSourceRowSchema).describe("세션 수 내림차순")
+});
+//#endregion
 //#region src/schemas/api-client.ts
 /**
 * 앱(OAuth 클라이언트) 관리 — `/v1/store/api-clients` (auth-spec 부록 B-13).
@@ -409,6 +539,72 @@ const categoryPatchRequestSchema = z.object({
 	metaKeywords: z.string().max(200).nullable().optional()
 });
 const categoryDeleteStrategySchema = z.enum(["reparent", "cascade"]);
+/**
+* `GET /v1/categories` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 응답 형태가 쿼리로 갈린다:
+* `q`가 있으면 검색 결과(`CategorySearchResult[]`), 아니면 `tree=true`일 때 트리(`CategoryTreeNode[]`),
+* 둘 다 아니면 목록(`Category[]`)이다.
+*/
+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 문서용 형태 */
+const categoryDeleteQuerySchema = z.object({ strategy: categoryDeleteStrategySchema.optional().describe("하위 카테고리·연결 상품 처리 방식. 생략하면 둘 중 하나라도 있을 때 409 `CATEGORY_NOT_EMPTY`다. `reparent`는 직계 자식을 삭제할 카테고리의 부모로 옮기고, `cascade`는 서브트리를 삭제하고 연결 상품을 미분류로 둔다") });
+//#endregion
+//#region src/schemas/common.ts
+const pageInfoSchema = z.object({
+	page: z.number().int(),
+	size: z.number().int(),
+	totalElements: z.number().int(),
+	totalPages: z.number().int()
+});
+function pageSchema(item) {
+	return pageInfoSchema.extend({ contents: z.array(item) });
+}
+/**
+* 목록 쿼리의 `page`·`size` — OpenAPI 문서용 형태(값은 쿼리 문자열). 서버는 숫자가 아니거나 범위를 벗어난
+* 값을 기본값·상한으로 보정한다.
+*/
+function pageQueryShape(options = {}) {
+	const { defaultSize = 20, maxSize = 100 } = options;
+	return {
+		page: z.string().optional().describe("페이지 번호 (1부터, 기본 1)"),
+		size: z.string().optional().describe(`페이지 크기 (기본 ${defaultSize}, 최대 ${maxSize})`)
+	};
+}
+const bulkResultSchema = z.object({
+	succeeded: z.array(z.string()),
+	failed: z.array(z.object({
+		id: z.string().optional(),
+		productId: z.string().optional(),
+		orderItemId: z.string().optional(),
+		code: z.string(),
+		message: z.string()
+	}))
+});
+const orderItemStatusSchema = z.enum([
+	"PAYMENT_WAITING",
+	"PAID",
+	"CONFIRMED",
+	"DISPATCHED",
+	"DELIVERING",
+	"DELIVERED",
+	"PURCHASE_DECIDED",
+	"CANCELED"
+]);
+const changeTypeSchema = z.enum([
+	"ORDER.PAID",
+	"ORDER.CONFIRMED",
+	"ORDER.DISPATCHED",
+	"ORDER.DELIVERED",
+	"ORDER.PURCHASE_DECIDED",
+	"CLAIM.CANCEL_REQUESTED",
+	"CLAIM.RETURN_REQUESTED",
+	"CLAIM.EXCHANGE_REQUESTED",
+	"ORDER.ADDRESS_CHANGE_REQUESTED"
+]);
 //#endregion
 //#region src/schemas/claim.ts
 const claimTypeSchema = z.enum([
@@ -460,6 +656,30 @@ const claimSchema = z.object({
 	requestedAt: z.string(),
 	completedAt: z.string().nullable()
 });
+/** `GET /v1/claims` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+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}` 응답 — 클레임 + 상태 이력 */
+const claimDetailSchema = claimSchema.extend({ histories: z.array(z.object({
+	status: claimStatusSchema,
+	actor: z.enum([
+		"BUYER",
+		"SELLER",
+		"SYSTEM"
+	]),
+	occurredAt: z.string()
+})).optional() });
+/** `POST /v1/claims/{claimId}/hold` 응답 */
+const claimHoldResultSchema = z.object({
+	claimId: z.string(),
+	holdExpiresAt: z.string()
+});
 const rejectClaimRequestSchema = z.object({
 	reason: z.enum([
 		"USED_PRODUCT",
@@ -478,48 +698,6 @@ const approveClaimResultSchema = z.object({
 	refundedAt: z.string()
 });
 //#endregion
-//#region src/schemas/common.ts
-const pageInfoSchema = z.object({
-	page: z.number().int(),
-	size: z.number().int(),
-	totalElements: z.number().int(),
-	totalPages: z.number().int()
-});
-function pageSchema(item) {
-	return pageInfoSchema.extend({ contents: z.array(item) });
-}
-const bulkResultSchema = z.object({
-	succeeded: z.array(z.string()),
-	failed: z.array(z.object({
-		id: z.string().optional(),
-		productId: z.string().optional(),
-		orderItemId: z.string().optional(),
-		code: z.string(),
-		message: z.string()
-	}))
-});
-const orderItemStatusSchema = z.enum([
-	"PAYMENT_WAITING",
-	"PAID",
-	"CONFIRMED",
-	"DISPATCHED",
-	"DELIVERING",
-	"DELIVERED",
-	"PURCHASE_DECIDED",
-	"CANCELED"
-]);
-const changeTypeSchema = z.enum([
-	"ORDER.PAID",
-	"ORDER.CONFIRMED",
-	"ORDER.DISPATCHED",
-	"ORDER.DELIVERED",
-	"ORDER.PURCHASE_DECIDED",
-	"CLAIM.CANCEL_REQUESTED",
-	"CLAIM.RETURN_REQUESTED",
-	"CLAIM.EXCHANGE_REQUESTED",
-	"ORDER.ADDRESS_CHANGE_REQUESTED"
-]);
-//#endregion
 //#region src/schemas/misc.ts
 const inquirySchema = z.object({
 	inquiryId: z.string(),
@@ -567,6 +745,21 @@ const sellerCustomerInquirySchema = z.object({
 	}).nullable(),
 	createdAt: z.string()
 });
+const answeredQuery = z.enum(["true", "false"]).optional().describe("답변 여부 필터. `true`면 답변된 문의만, `false`면 미답변만, 생략하면 전부");
+/** `GET /v1/inquiries` 쿼리(상품 문의) — OpenAPI 문서용 형태(값은 쿼리 문자열). 최신순이다 */
+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 문서용 형태(값은 쿼리 문자열). 최신순이다 */
+const customerInquiryListQuerySchema = z.object({
+	answered: answeredQuery,
+	category: customerInquiryCategorySchema.optional().describe("문의 유형 필터"),
+	from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
+	...pageQueryShape()
+});
 const settlementStatusSchema = z.enum([
 	"SCHEDULED",
 	"PAID",
@@ -600,6 +793,20 @@ const settlementDetailSchema = z.object({
 	settlementAmount: z.number().int(),
 	purchaseDecidedAt: z.string().nullable()
 });
+/** `GET /v1/settlements/{settlementId}` 응답 — 정산 요약 + 상세 내역(`size`건까지) */
+const settlementWithDetailsSchema = settlementSummarySchema.extend({ details: z.array(settlementDetailSchema).optional() });
+/** `GET /v1/settlements` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 정산일 최신순이다 */
+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`는 무시) */
+const settlementDetailQuerySchema = z.object(pageQueryShape({
+	defaultSize: 100,
+	maxSize: 300
+}));
 const eventTypeSchema = z.enum([
 	"ORDER.PAID",
 	"ORDER.CONFIRMED",
@@ -699,6 +906,33 @@ const reviewSchema = z.object({
 	}).nullable(),
 	createdAt: z.string()
 });
+const reviewSortSchema = z.enum([
+	"createdAt.desc",
+	"createdAt.asc",
+	"rating.asc",
+	"rating.desc"
+]);
+/** `GET /v1/reviews` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+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) — 신고 접수 */
+const reviewReportResultSchema = z.object({
+	reviewId: z.string(),
+	status: z.literal("PENDING_REVIEW")
+});
 //#endregion
 //#region src/schemas/order.ts
 const orderSummarySchema = z.object({
@@ -835,6 +1069,18 @@ const deliveryInfoSchema = z.object({
 	dispatchedAt: z.string(),
 	deliveredAt: z.string().nullable()
 });
+/** `GET /v1/order-items/{orderItemId}/delivery` 응답 — 배송 정보 + 배송 추적 이벤트 */
+const deliveryStatusSchema = deliveryInfoSchema.extend({ trackingEvents: z.array(z.object({
+	status: z.string(),
+	location: z.string(),
+	occurredAt: z.string()
+})).optional() });
+/** `PUT /v1/order-items/{orderItemId}/dispatch/tracking` 응답 — 바뀐 송장 */
+const trackingUpdateResultSchema = z.object({
+	orderItemId: z.string(),
+	carrierCode: z.string(),
+	trackingNumber: z.string()
+});
 const carrierSchema = z.object({
 	carrierCode: z.string(),
 	name: z.string(),
@@ -859,6 +1105,33 @@ const cancelBySellerRequestSchema = z.object({
 	]),
 	detail: z.string().max(500).optional()
 });
+/** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
+const cancelBySellerResultSchema = z.object({
+	orderItemId: z.string(),
+	refundAmount: z.number().int(),
+	refundedAt: z.string()
+});
+/** `PUT /v1/order-items/{orderItemId}/memo` 응답 — 빈 문자열로 저장하면 메모가 지워져 `null`이다 */
+const orderItemMemoResultSchema = z.object({
+	orderItemId: z.string(),
+	sellerMemo: z.string().nullable()
+});
+/** `POST /v1/order-items/{orderItemId}/purchase-decision/request` 응답 */
+const purchaseDecisionRequestResultSchema = z.object({
+	orderItemId: z.string(),
+	requestedAt: z.string()
+});
+/** `POST /v1/order-items/{orderItemId}/purchase-decision/extend` 응답 — 연장은 최대 2회 */
+const purchaseDecisionExtendResultSchema = z.object({
+	orderItemId: z.string(),
+	autoDecisionDate: z.string(),
+	extendCount: z.number().int().max(2)
+});
+/**
+* `GET /v1/orders/{orderId}/address-change-requests` 응답 — 배송지 변경 요청 플로우는 아직 제공하지 않아
+* 현재는 항상 빈 배열이다
+*/
+const addressChangeRequestListSchema = z.array(z.record(z.string(), z.unknown())).describe("배송지 변경 요청 목록 (현재 항상 빈 배열)");
 //#endregion
 //#region src/schemas/payment.ts
 /**
@@ -1340,6 +1613,28 @@ const productPatchRequestSchema = z.object({
 	status: productStatusSchema.optional(),
 	deliveryFee: z.number().int().optional()
 }).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
+const productSortSchema = z.enum([
+	"createdAt.desc",
+	"createdAt.asc",
+	"salePrice.asc",
+	"salePrice.desc",
+	"updatedAt.desc"
+]);
+/** `GET /v1/products` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+const productListQuerySchema = z.object({
+	status: productStatusSchema.optional().describe("판매 상태 필터"),
+	categoryId: z.string().optional().describe("카테고리 필터 — 하위 카테고리의 상품도 포함"),
+	keyword: z.string().optional().describe("상품명 검색 (포함)"),
+	sellerCode: z.string().optional().describe("판매자 상품코드 — 이 코드가 붙은 variant를 가진 상품"),
+	sort: productSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
+	...pageQueryShape()
+});
+/** `POST /v1/product-images` 응답 — 업로드된 이미지의 CDN 주소 */
+const productImageUploadResultSchema = z.object({ images: z.array(z.object({
+	url: z.url(),
+	width: z.number().int(),
+	height: z.number().int()
+})) });
 const discountSchema = z.object({
 	productId: z.string(),
 	discountType: z.enum(["RATE", "AMOUNT"]),
@@ -1453,7 +1748,16 @@ const invitationSchema = z.object({
 	expiresAt: z.string(),
 	createdAt: z.string()
 });
+/** `GET /v1/store/invitations` 쿼리 — OpenAPI 문서용 형태 */
+const invitationListQuerySchema = z.object({ status: invitationSchema.shape.status.optional().describe("초대 상태 필터") });
+/** `PATCH /v1/store/members/{userId}` 응답 — 바뀐 역할 */
+const storeMemberRoleUpdatedSchema = z.object({
+	userId: z.string(),
+	role: z.enum(["ADMIN", "STAFF"])
+});
 const addressTypeSchema = z.enum(["SHIPPING", "RETURN"]);
+/** `GET /v1/seller-addresses` 쿼리 — OpenAPI 문서용 형태. 기본 주소 우선, 그다음 등록순이다 */
+const sellerAddressListQuerySchema = z.object({ type: addressTypeSchema.optional().describe("주소 유형 필터") });
 const sellerAddressSchema = z.object({
 	addressId: z.string(),
 	type: addressTypeSchema,
@@ -1681,21 +1985,13 @@ function createStoreClient(options) {
 			}),
 			hold: (orderItemId, body) => storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/hold`, { body: holdOrderItemRequestSchema.parse(body) }),
 			releaseHold: (orderItemId) => storeHttp.requestVoid("DELETE", path`/order-items/${orderItemId}/hold`),
-			cancelBySeller: (orderItemId, body, idempotencyKey) => storeHttp.request("POST", path`/order-items/${orderItemId}/cancel`, z.object({
-				orderItemId: z.string(),
-				refundAmount: z.number().int(),
-				refundedAt: z.string()
-			}), {
+			cancelBySeller: (orderItemId, body, idempotencyKey) => storeHttp.request("POST", path`/order-items/${orderItemId}/cancel`, cancelBySellerResultSchema, {
 				body: cancelBySellerRequestSchema.parse(body),
 				headers: idempotency(idempotencyKey)
 			}),
 			updateMemo: (orderItemId, memo) => storeHttp.requestVoid("PUT", path`/order-items/${orderItemId}/memo`, { body: { memo } }),
 			requestPurchaseDecision: (orderItemId) => storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/purchase-decision/request`),
-			extendPurchaseDecision: (orderItemId) => storeHttp.request("POST", path`/order-items/${orderItemId}/purchase-decision/extend`, z.object({
-				orderItemId: z.string(),
-				autoDecisionDate: z.string(),
-				extendCount: z.number().int().max(2)
-			})),
+			extendPurchaseDecision: (orderItemId) => storeHttp.request("POST", path`/order-items/${orderItemId}/purchase-decision/extend`, purchaseDecisionExtendResultSchema),
 			dispatch: (orderItemId, body, idempotencyKey) => storeHttp.request("POST", path`/order-items/${orderItemId}/dispatch`, deliveryInfoSchema, {
 				body: dispatchRequestSchema.parse(body),
 				headers: idempotency(idempotencyKey)
@@ -1708,24 +2004,12 @@ function createStoreClient(options) {
 				carrierCode,
 				trackingNumber
 			} }),
-			getDelivery: (orderItemId) => 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() }))
+			getDelivery: (orderItemId) => storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema)
 		},
 		carriers: { list: () => storeHttp.request("GET", "/carriers", z.array(carrierSchema)) },
 		claims: {
 			list: (params) => storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: params }),
-			get: (claimId) => 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() })),
+			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 } : {},
 				headers: idempotency(idempotencyKey)
@@ -1737,10 +2021,7 @@ function createStoreClient(options) {
 				carrierCode,
 				trackingNumber
 			} }),
-			hold: (claimId, reason) => storeHttp.request("POST", path`/claims/${claimId}/hold`, z.object({
-				claimId: z.string(),
-				holdExpiresAt: z.string()
-			}), { body: { reason } }),
+			hold: (claimId, reason) => storeHttp.request("POST", path`/claims/${claimId}/hold`, claimHoldResultSchema, { body: { reason } }),
 			releaseHold: (claimId) => storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`)
 		},
 		inquiries: {
@@ -1763,7 +2044,7 @@ function createStoreClient(options) {
 			/** @deprecated `salesReport.get`을 쓴다. 기존 정산 레코드 조회만 유지된다 */
 			list: (params) => storeHttp.request("GET", "/settlements", pageSchema(settlementSummarySchema), { query: params }),
 			/** @deprecated `salesReport.get`을 쓴다. 기존 정산 레코드 조회만 유지된다 */
-			get: (settlementId, params) => storeHttp.request("GET", path`/settlements/${settlementId}`, settlementSummarySchema.extend({ details: z.array(settlementDetailSchema).optional() }), { query: params })
+			get: (settlementId, params) => storeHttp.request("GET", path`/settlements/${settlementId}`, settlementWithDetailsSchema, { query: params })
 		},
 		/**
 		* 매출 리포트 (정산 API 대체) — 스코프 `settlement:r`. PG 승인 시각 기준 결제, PG 취소 완료 시각 기준
@@ -1776,6 +2057,19 @@ function createStoreClient(options) {
 		* 400 `INVALID_PARAMETER`(없는 날짜·to<from), 400 `RANGE_TOO_WIDE`(기간 초과)
 		*/
 get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, { query: salesReportQuerySchema.parse(params) }) },
+		/**
+		* 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+		* 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
+		* 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
+		*/
+		analytics: {
+			/** `GET /v1/analytics/overview` — 합계·세션 퍼널·날짜별 값 */
+			overview: (params) => storeHttp.request("GET", "/analytics/overview", analyticsOverviewSchema, { query: analyticsRangeQuerySchema.parse(params) }),
+			/** `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) })
+		},
 		/**
 		* 결제 내역 — 스코프 `settlement:r`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
 		* 결제(카드 거절·결제창 이탈·승인 결과 확인 중)도 그대로 나온다.
@@ -2011,7 +2305,7 @@ async function exchangeStoreTokenViaOAuth(options) {
 * 서버 인가가 갈라지지 않는다.
 */
 const scopeAccessSchema = z.enum(["r", "rw"]).describe("접근 수준. `r`=읽기, `rw`=읽기+쓰기(r을 함의)");
-/** 리소스별로 부여 가능한 접근 수준. settlement는 쓰기 API가 없어 `r`만 존재한다 */
+/** 리소스별로 부여 가능한 접근 수준. settlement·analytics는 쓰기 API가 없어 `r`만 존재한다 */
 const STORE_SCOPE_RESOURCES = {
 	product: ["r", "rw"],
 	category: ["r", "rw"],
@@ -2020,6 +2314,7 @@ const STORE_SCOPE_RESOURCES = {
 	inquiry: ["r", "rw"],
 	review: ["r", "rw"],
 	settlement: ["r"],
+	analytics: ["r"],
 	webhook: ["r", "rw"],
 	store: ["r", "rw"],
 	member: ["r", "rw"]
@@ -2045,6 +2340,7 @@ const STORE_ROLE_SCOPES = {
 		"inquiry:rw",
 		"review:rw",
 		"settlement:r",
+		"analytics:r",
 		"webhook:rw",
 		"store:rw",
 		"member:rw"
@@ -2056,6 +2352,7 @@ const STORE_ROLE_SCOPES = {
 		"claim:rw",
 		"inquiry:rw",
 		"review:rw",
+		"analytics:r",
 		"webhook:rw",
 		"store:rw",
 		"member:rw"
@@ -2297,4 +2594,4 @@ function createStoreSession(options) {
 	};
 }
 //#endregion
-export { ApiError, 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, addressTypeSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approveClaimResultSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, carrierSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteStrategySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimReasonSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, createPkcePair, createStoreClient, createStoreSession, customerInquiryCategorySchema, deliveryInfoSchema, deliveryMethodSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, effectivePaymentRoutingModeSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationSchema, isReservedStoreCode, isStoreScope, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentRoutingModeSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, refreshUserToken, rejectClaimRequestSchema, reviewSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, scopeAccessSchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailSchema, settlementStatusSchema, settlementSummarySchema, shippingAddressSchema, storeCodeSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema };
+export { ApiError, 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, 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, customerInquiryCategorySchema, customerInquiryListQuerySchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, effectivePaymentRoutingModeSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationListQuerySchema, invitationSchema, isReservedStoreCode, isStoreScope, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, 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, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingUpdateResultSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {
@@ -31,7 +31,7 @@
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cochoio/shop.24.git"
+    "url": "git+https://github.com/avarcorp/sayren.git"
   },
   "files": [
     "dist",