@sayren/store-sdk 0.6.0 → 0.7.0

package/dist/index.d.mts

@@ -100,6 +100,7 @@ export declare const analyticsOverviewSchema: z.ZodObject<{
     conversionRate: z.ZodNullable<z.ZodNumber>;
     date: z.ZodString;
   }, z.core.$strip>>;
+  excludedBotSessions: z.ZodNumber;
   from: z.ZodString;
   to: z.ZodString;
   timezone: z.ZodLiteral<"Asia/Seoul">;
@@ -144,6 +145,7 @@ export declare const analyticsProductRowSchema: z.ZodObject<{
   quantity: z.ZodNumber;
   revenue: z.ZodNumber;
   purchaseRate: z.ZodNullable<z.ZodNumber>;
+  clickThroughRate: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 export type AnalyticsProductRow = z.infer<typeof analyticsProductRowSchema>;
 export declare const analyticsProductsSchema: z.ZodObject<{
@@ -165,6 +167,7 @@ export declare const analyticsProductsSchema: z.ZodObject<{
     quantity: z.ZodNumber;
     revenue: z.ZodNumber;
     purchaseRate: z.ZodNullable<z.ZodNumber>;
+    clickThroughRate: z.ZodNullable<z.ZodNumber>;
   }, z.core.$strip>>;
   from: z.ZodString;
   to: z.ZodString;
@@ -279,6 +282,159 @@ export declare const analyticsSourcesSchema: z.ZodObject<{
   lastComputedAt: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type AnalyticsSources = z.infer<typeof analyticsSourcesSchema>;
+export declare const analyticsRealtimeSchema: z.ZodObject<{
+  asOf: z.ZodString;
+  windowMinutes: z.ZodLiteral<5>;
+  visitors: z.ZodNumber;
+  sessions: z.ZodNumber;
+  pageViews: z.ZodNumber;
+  pages: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    visitors: z.ZodNumber;
+    pageViews: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AnalyticsRealtime = z.infer<typeof analyticsRealtimeSchema>;
+export declare const analyticsDeviceRowSchema: z.ZodObject<{
+  device: z.ZodEnum<{
+    unknown: "unknown";
+    desktop: "desktop";
+    mobile: "mobile";
+    tablet: "tablet";
+  }>;
+  sessions: z.ZodNumber;
+  productViewSessions: z.ZodNumber;
+  addToCartSessions: z.ZodNumber;
+  beginCheckoutSessions: z.ZodNumber;
+  purchaseSessions: z.ZodNumber;
+  conversionRate: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type AnalyticsDeviceRow = z.infer<typeof analyticsDeviceRowSchema>;
+export declare const analyticsDevicesSchema: z.ZodObject<{
+  rows: z.ZodArray<z.ZodObject<{
+    device: z.ZodEnum<{
+      unknown: "unknown";
+      desktop: "desktop";
+      mobile: "mobile";
+      tablet: "tablet";
+    }>;
+    sessions: z.ZodNumber;
+    productViewSessions: z.ZodNumber;
+    addToCartSessions: z.ZodNumber;
+    beginCheckoutSessions: z.ZodNumber;
+    purchaseSessions: z.ZodNumber;
+    conversionRate: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  from: z.ZodString;
+  to: z.ZodString;
+  timezone: z.ZodLiteral<"Asia/Seoul">;
+  currency: z.ZodLiteral<"KRW">;
+  includeTest: z.ZodBoolean;
+  lastComputedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AnalyticsDevices = z.infer<typeof analyticsDevicesSchema>;
+export declare const analyticsPagesQuerySchema: z.ZodObject<{
+  from: z.ZodString;
+  to: z.ZodString;
+  includeTest: z.ZodOptional<z.ZodEnum<{
+    true: "true";
+    false: "false";
+  }>>;
+  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type AnalyticsPagesParams = z.infer<typeof analyticsPagesQuerySchema>;
+export declare const analyticsPagesSchema: z.ZodObject<{
+  landings: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    entrances: z.ZodNumber;
+    bounces: z.ZodNumber;
+    bounceRate: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  exits: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    pageViews: z.ZodNumber;
+    exits: z.ZodNumber;
+    exitRate: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  from: z.ZodString;
+  to: z.ZodString;
+  timezone: z.ZodLiteral<"Asia/Seoul">;
+  currency: z.ZodLiteral<"KRW">;
+  includeTest: z.ZodBoolean;
+  lastComputedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AnalyticsPages = z.infer<typeof analyticsPagesSchema>;
+export declare const analyticsSearchQuerySchema: z.ZodObject<{
+  from: z.ZodString;
+  to: z.ZodString;
+  includeTest: z.ZodOptional<z.ZodEnum<{
+    true: "true";
+    false: "false";
+  }>>;
+  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type AnalyticsSearchParams = z.infer<typeof analyticsSearchQuerySchema>;
+export declare const analyticsSearchSchema: z.ZodObject<{
+  summary: z.ZodObject<{
+    searches: z.ZodNumber;
+    zeroResultSearches: z.ZodNumber;
+    searchSessions: z.ZodNumber;
+    purchaseSessions: z.ZodNumber;
+    conversionRate: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>;
+  terms: z.ZodArray<z.ZodObject<{
+    term: z.ZodString;
+    searches: z.ZodNumber;
+    zeroResultSearches: z.ZodNumber;
+    searchSessions: z.ZodNumber;
+    purchaseSessions: z.ZodNumber;
+    conversionRate: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  zeroResultTerms: z.ZodArray<z.ZodObject<{
+    term: z.ZodString;
+    searches: z.ZodNumber;
+    zeroResultSearches: z.ZodNumber;
+  }, z.core.$strip>>;
+  from: z.ZodString;
+  to: z.ZodString;
+  timezone: z.ZodLiteral<"Asia/Seoul">;
+  currency: z.ZodLiteral<"KRW">;
+  includeTest: z.ZodBoolean;
+  lastComputedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AnalyticsSearch = z.infer<typeof analyticsSearchSchema>;
+export declare const analyticsCheckoutOutcomeSchema: z.ZodEnum<{
+  OTHER: "OTHER";
+  COMPLETED: "COMPLETED";
+  NOT_OPENED: "NOT_OPENED";
+  USER_CANCELED: "USER_CANCELED";
+  DECLINED: "DECLINED";
+  PREPARE_FAILURE: "PREPARE_FAILURE";
+  IN_PROGRESS: "IN_PROGRESS";
+}>;
+export type AnalyticsCheckoutOutcome = z.infer<typeof analyticsCheckoutOutcomeSchema>;
+export declare const analyticsCheckoutSchema: z.ZodObject<{
+  sessions: z.ZodNumber;
+  outcomes: z.ZodArray<z.ZodObject<{
+    outcome: z.ZodEnum<{
+      OTHER: "OTHER";
+      COMPLETED: "COMPLETED";
+      NOT_OPENED: "NOT_OPENED";
+      USER_CANCELED: "USER_CANCELED";
+      DECLINED: "DECLINED";
+      PREPARE_FAILURE: "PREPARE_FAILURE";
+      IN_PROGRESS: "IN_PROGRESS";
+    }>;
+    sessions: z.ZodNumber;
+  }, z.core.$strip>>;
+  from: z.ZodString;
+  to: z.ZodString;
+  timezone: z.ZodLiteral<"Asia/Seoul">;
+  currency: z.ZodLiteral<"KRW">;
+  includeTest: z.ZodBoolean;
+  lastComputedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AnalyticsCheckout = z.infer<typeof analyticsCheckoutSchema>;
 //#endregion
 //#region src/schemas/api-client.d.ts
 /**
@@ -5065,6 +5221,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         conversionRate: number | null;
         date: string;
       }[];
+      excludedBotSessions: number;
       from: string;
       to: string;
       timezone: "Asia/Seoul";
@@ -5086,6 +5243,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         quantity: number;
         revenue: number;
         purchaseRate: number | null;
+        clickThroughRate: number | null;
       }[];
       from: string;
       to: string;
@@ -5118,6 +5276,101 @@ export declare function createStoreClient(options: StoreClientOptions): {
       includeTest: boolean;
       lastComputedAt: string | null;
     }>;
+    /** `GET /v1/analytics/realtime` — 최근 5분 방문자·세션·페이지(원본 이벤트 기준, 봇 제외) */
+    realtime: () => Promise<{
+      asOf: string;
+      windowMinutes: 5;
+      visitors: number;
+      sessions: number;
+      pageViews: number;
+      pages: {
+        path: string;
+        visitors: number;
+        pageViews: number;
+      }[];
+    }>;
+    /** `GET /v1/analytics/devices` — 기기별 세션 퍼널 */
+    devices: (params: AnalyticsRangeParams) => Promise<{
+      rows: {
+        device: "unknown" | "desktop" | "mobile" | "tablet";
+        sessions: number;
+        productViewSessions: number;
+        addToCartSessions: number;
+        beginCheckoutSessions: number;
+        purchaseSessions: number;
+        conversionRate: number | null;
+      }[];
+      from: string;
+      to: string;
+      timezone: "Asia/Seoul";
+      currency: "KRW";
+      includeTest: boolean;
+      lastComputedAt: string | null;
+    }>;
+    /** `GET /v1/analytics/pages` — 첫 페이지(진입·반송)와 이탈 페이지 */
+    pages: (params: AnalyticsPagesParams) => Promise<{
+      landings: {
+        path: string;
+        entrances: number;
+        bounces: number;
+        bounceRate: number | null;
+      }[];
+      exits: {
+        path: string;
+        pageViews: number;
+        exits: number;
+        exitRate: number | null;
+      }[];
+      from: string;
+      to: string;
+      timezone: "Asia/Seoul";
+      currency: "KRW";
+      includeTest: boolean;
+      lastComputedAt: string | null;
+    }>;
+    /** `GET /v1/analytics/search` — 검색어별 검색·결과 0개·검색 후 구매 */
+    search: (params: AnalyticsSearchParams) => Promise<{
+      summary: {
+        searches: number;
+        zeroResultSearches: number;
+        searchSessions: number;
+        purchaseSessions: number;
+        conversionRate: number | null;
+      };
+      terms: {
+        term: string;
+        searches: number;
+        zeroResultSearches: number;
+        searchSessions: number;
+        purchaseSessions: number;
+        conversionRate: number | null;
+      }[];
+      zeroResultTerms: {
+        term: string;
+        searches: number;
+        zeroResultSearches: number;
+      }[];
+      from: string;
+      to: string;
+      timezone: "Asia/Seoul";
+      currency: "KRW";
+      includeTest: boolean;
+      lastComputedAt: string | null;
+    }>;
+    /** `GET /v1/analytics/checkout` — 결제 세션의 결과별 수(결제 단계 이탈 이유) */
+    checkout: (params: AnalyticsRangeParams) => Promise<{
+      sessions: number;
+      outcomes: {
+        outcome: "OTHER" | "COMPLETED" | "NOT_OPENED" | "USER_CANCELED" | "DECLINED" | "PREPARE_FAILURE" | "IN_PROGRESS";
+        sessions: number;
+      }[];
+      from: string;
+      to: string;
+      timezone: "Asia/Seoul";
+      currency: "KRW";
+      includeTest: boolean;
+      lastComputedAt: string | null;
+    }>;
   };
   /**
    * 결제 내역 — 스코프 `settlement:r`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은

package/dist/index.mjs

@@ -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
 /**
@@ -2277,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`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
@@ -2812,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.6.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";
@@ -719,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),
+        }),
     },
 
     /**

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";
+  }
+}

package/src/schemas/analytics.ts

@@ -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/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,