@sayren/store-sdk 0.1.1 → 0.2.0

package/dist/index.d.mts

@@ -16,6 +16,270 @@ type TokenSource = string | null | undefined | (() => string | null | undefined)
 type Query = Record<string, string | number | boolean | undefined>;
 export declare function buildQuery(query?: Query): string;
 //#endregion
+//#region src/schemas/analytics.d.ts
+export declare const analyticsRangeQuerySchema: z.ZodObject<{
+  from: z.ZodString;
+  to: z.ZodString;
+  includeTest: z.ZodOptional<z.ZodEnum<{
+    true: "true";
+    false: "false";
+  }>>;
+}, z.core.$strip>;
+export type AnalyticsRangeParams = z.infer<typeof analyticsRangeQuerySchema>;
+export declare const analyticsTotalsSchema: z.ZodObject<{
+  visitors: z.ZodNumber;
+  sessions: z.ZodNumber;
+  engagedSessions: z.ZodNumber;
+  pageViews: z.ZodNumber;
+  engagementSeconds: z.ZodNumber;
+  productViews: z.ZodNumber;
+  productViewSessions: z.ZodNumber;
+  addToCartSessions: z.ZodNumber;
+  beginCheckoutSessions: z.ZodNumber;
+  purchaseSessions: z.ZodNumber;
+  purchases: z.ZodNumber;
+  revenue: z.ZodNumber;
+  engagementRate: z.ZodNullable<z.ZodNumber>;
+  conversionRate: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type AnalyticsTotals = z.infer<typeof analyticsTotalsSchema>;
+export declare const analyticsFunnelStepSchema: z.ZodObject<{
+  step: z.ZodEnum<{
+    SESSION: "SESSION";
+    PRODUCT_VIEW: "PRODUCT_VIEW";
+    ADD_TO_CART: "ADD_TO_CART";
+    BEGIN_CHECKOUT: "BEGIN_CHECKOUT";
+    PURCHASE: "PURCHASE";
+  }>;
+  sessions: z.ZodNumber;
+  rateFromPrevious: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type AnalyticsFunnelStep = z.infer<typeof analyticsFunnelStepSchema>;
+export declare const analyticsOverviewSchema: z.ZodObject<{
+  summary: z.ZodObject<{
+    visitors: z.ZodNumber;
+    sessions: z.ZodNumber;
+    engagedSessions: z.ZodNumber;
+    pageViews: z.ZodNumber;
+    engagementSeconds: z.ZodNumber;
+    productViews: z.ZodNumber;
+    productViewSessions: z.ZodNumber;
+    addToCartSessions: z.ZodNumber;
+    beginCheckoutSessions: z.ZodNumber;
+    purchaseSessions: z.ZodNumber;
+    purchases: z.ZodNumber;
+    revenue: z.ZodNumber;
+    engagementRate: z.ZodNullable<z.ZodNumber>;
+    conversionRate: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>;
+  funnel: z.ZodArray<z.ZodObject<{
+    step: z.ZodEnum<{
+      SESSION: "SESSION";
+      PRODUCT_VIEW: "PRODUCT_VIEW";
+      ADD_TO_CART: "ADD_TO_CART";
+      BEGIN_CHECKOUT: "BEGIN_CHECKOUT";
+      PURCHASE: "PURCHASE";
+    }>;
+    sessions: z.ZodNumber;
+    rateFromPrevious: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  rows: z.ZodArray<z.ZodObject<{
+    visitors: z.ZodNumber;
+    sessions: z.ZodNumber;
+    engagedSessions: z.ZodNumber;
+    pageViews: z.ZodNumber;
+    engagementSeconds: z.ZodNumber;
+    productViews: z.ZodNumber;
+    productViewSessions: z.ZodNumber;
+    addToCartSessions: z.ZodNumber;
+    beginCheckoutSessions: z.ZodNumber;
+    purchaseSessions: z.ZodNumber;
+    purchases: z.ZodNumber;
+    revenue: z.ZodNumber;
+    engagementRate: z.ZodNullable<z.ZodNumber>;
+    conversionRate: z.ZodNullable<z.ZodNumber>;
+    date: z.ZodString;
+  }, 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 AnalyticsOverview = z.infer<typeof analyticsOverviewSchema>;
+export declare const analyticsProductSortSchema: z.ZodEnum<{
+  VIEWS: "VIEWS";
+  ADD_TO_CARTS: "ADD_TO_CARTS";
+  PURCHASES: "PURCHASES";
+  REVENUE: "REVENUE";
+  IMPRESSIONS: "IMPRESSIONS";
+}>;
+export type AnalyticsProductSort = z.infer<typeof analyticsProductSortSchema>;
+export declare const analyticsProductsQuerySchema: z.ZodObject<{
+  from: z.ZodString;
+  to: z.ZodString;
+  includeTest: z.ZodOptional<z.ZodEnum<{
+    true: "true";
+    false: "false";
+  }>>;
+  sort: z.ZodOptional<z.ZodEnum<{
+    VIEWS: "VIEWS";
+    ADD_TO_CARTS: "ADD_TO_CARTS";
+    PURCHASES: "PURCHASES";
+    REVENUE: "REVENUE";
+    IMPRESSIONS: "IMPRESSIONS";
+  }>>;
+  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type AnalyticsProductsParams = z.infer<typeof analyticsProductsQuerySchema>;
+export declare const analyticsProductRowSchema: z.ZodObject<{
+  productId: z.ZodString;
+  productName: z.ZodNullable<z.ZodString>;
+  impressions: z.ZodNumber;
+  views: z.ZodNumber;
+  viewSessions: z.ZodNumber;
+  addToCarts: z.ZodNumber;
+  purchases: z.ZodNumber;
+  quantity: z.ZodNumber;
+  revenue: z.ZodNumber;
+  purchaseRate: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type AnalyticsProductRow = z.infer<typeof analyticsProductRowSchema>;
+export declare const analyticsProductsSchema: z.ZodObject<{
+  sort: z.ZodEnum<{
+    VIEWS: "VIEWS";
+    ADD_TO_CARTS: "ADD_TO_CARTS";
+    PURCHASES: "PURCHASES";
+    REVENUE: "REVENUE";
+    IMPRESSIONS: "IMPRESSIONS";
+  }>;
+  rows: z.ZodArray<z.ZodObject<{
+    productId: z.ZodString;
+    productName: z.ZodNullable<z.ZodString>;
+    impressions: z.ZodNumber;
+    views: z.ZodNumber;
+    viewSessions: z.ZodNumber;
+    addToCarts: z.ZodNumber;
+    purchases: z.ZodNumber;
+    quantity: z.ZodNumber;
+    revenue: z.ZodNumber;
+    purchaseRate: 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 AnalyticsProducts = z.infer<typeof analyticsProductsSchema>;
+export declare const analyticsChannelSchema: z.ZodEnum<{
+  PAID: "PAID";
+  DIRECT: "DIRECT";
+  CAMPAIGN: "CAMPAIGN";
+  ORGANIC_SEARCH: "ORGANIC_SEARCH";
+  SOCIAL: "SOCIAL";
+  EMAIL: "EMAIL";
+  REFERRAL: "REFERRAL";
+  UNKNOWN: "UNKNOWN";
+}>;
+export type AnalyticsChannel = z.infer<typeof analyticsChannelSchema>;
+export declare const analyticsSourceGroupBySchema: z.ZodEnum<{
+  CHANNEL: "CHANNEL";
+  SOURCE: "SOURCE";
+  CAMPAIGN: "CAMPAIGN";
+  DEVICE: "DEVICE";
+}>;
+export type AnalyticsSourceGroupBy = z.infer<typeof analyticsSourceGroupBySchema>;
+export declare const analyticsSourcesQuerySchema: z.ZodObject<{
+  from: z.ZodString;
+  to: z.ZodString;
+  includeTest: z.ZodOptional<z.ZodEnum<{
+    true: "true";
+    false: "false";
+  }>>;
+  groupBy: z.ZodOptional<z.ZodEnum<{
+    CHANNEL: "CHANNEL";
+    SOURCE: "SOURCE";
+    CAMPAIGN: "CAMPAIGN";
+    DEVICE: "DEVICE";
+  }>>;
+}, z.core.$strip>;
+export type AnalyticsSourcesParams = z.infer<typeof analyticsSourcesQuerySchema>;
+export declare const analyticsSourceRowSchema: z.ZodObject<{
+  channel: z.ZodNullable<z.ZodEnum<{
+    PAID: "PAID";
+    DIRECT: "DIRECT";
+    CAMPAIGN: "CAMPAIGN";
+    ORGANIC_SEARCH: "ORGANIC_SEARCH";
+    SOCIAL: "SOCIAL";
+    EMAIL: "EMAIL";
+    REFERRAL: "REFERRAL";
+    UNKNOWN: "UNKNOWN";
+  }>>;
+  source: z.ZodNullable<z.ZodString>;
+  medium: z.ZodNullable<z.ZodString>;
+  campaign: z.ZodNullable<z.ZodString>;
+  device: z.ZodNullable<z.ZodEnum<{
+    unknown: "unknown";
+    desktop: "desktop";
+    mobile: "mobile";
+    tablet: "tablet";
+  }>>;
+  sessions: z.ZodNumber;
+  visitors: z.ZodNumber;
+  engagedSessions: z.ZodNumber;
+  purchaseSessions: z.ZodNumber;
+  purchases: z.ZodNumber;
+  revenue: z.ZodNumber;
+  conversionRate: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type AnalyticsSourceRow = z.infer<typeof analyticsSourceRowSchema>;
+export declare const analyticsSourcesSchema: z.ZodObject<{
+  groupBy: z.ZodEnum<{
+    CHANNEL: "CHANNEL";
+    SOURCE: "SOURCE";
+    CAMPAIGN: "CAMPAIGN";
+    DEVICE: "DEVICE";
+  }>;
+  rows: z.ZodArray<z.ZodObject<{
+    channel: z.ZodNullable<z.ZodEnum<{
+      PAID: "PAID";
+      DIRECT: "DIRECT";
+      CAMPAIGN: "CAMPAIGN";
+      ORGANIC_SEARCH: "ORGANIC_SEARCH";
+      SOCIAL: "SOCIAL";
+      EMAIL: "EMAIL";
+      REFERRAL: "REFERRAL";
+      UNKNOWN: "UNKNOWN";
+    }>>;
+    source: z.ZodNullable<z.ZodString>;
+    medium: z.ZodNullable<z.ZodString>;
+    campaign: z.ZodNullable<z.ZodString>;
+    device: z.ZodNullable<z.ZodEnum<{
+      unknown: "unknown";
+      desktop: "desktop";
+      mobile: "mobile";
+      tablet: "tablet";
+    }>>;
+    sessions: z.ZodNumber;
+    visitors: z.ZodNumber;
+    engagedSessions: z.ZodNumber;
+    purchaseSessions: z.ZodNumber;
+    purchases: z.ZodNumber;
+    revenue: 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 AnalyticsSources = z.infer<typeof analyticsSourcesSchema>;
+//#endregion
 //#region src/schemas/api-client.d.ts
 /**
  * 앱(OAuth 클라이언트) 관리 — `/v1/store/api-clients` (auth-spec 부록 B-13).
@@ -4318,6 +4582,106 @@ export declare function createStoreClient(options: StoreClientOptions): {
       }[];
     }>;
   };
+  /**
+   * 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+   * 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
+   * 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
+   */
+  analytics: {
+    /** `GET /v1/analytics/overview` — 합계·세션 퍼널·날짜별 값 */
+    overview: (params: AnalyticsRangeParams) => Promise<{
+      summary: {
+        visitors: number;
+        sessions: number;
+        engagedSessions: number;
+        pageViews: number;
+        engagementSeconds: number;
+        productViews: number;
+        productViewSessions: number;
+        addToCartSessions: number;
+        beginCheckoutSessions: number;
+        purchaseSessions: number;
+        purchases: number;
+        revenue: number;
+        engagementRate: number | null;
+        conversionRate: number | null;
+      };
+      funnel: {
+        step: "SESSION" | "PRODUCT_VIEW" | "ADD_TO_CART" | "BEGIN_CHECKOUT" | "PURCHASE";
+        sessions: number;
+        rateFromPrevious: number | null;
+      }[];
+      rows: {
+        visitors: number;
+        sessions: number;
+        engagedSessions: number;
+        pageViews: number;
+        engagementSeconds: number;
+        productViews: number;
+        productViewSessions: number;
+        addToCartSessions: number;
+        beginCheckoutSessions: number;
+        purchaseSessions: number;
+        purchases: number;
+        revenue: number;
+        engagementRate: number | null;
+        conversionRate: number | null;
+        date: string;
+      }[];
+      from: string;
+      to: string;
+      timezone: "Asia/Seoul";
+      currency: "KRW";
+      includeTest: boolean;
+      lastComputedAt: string | null;
+    }>;
+    /** `GET /v1/analytics/products` — 상품별 노출·조회·장바구니·구매 */
+    products: (params: AnalyticsProductsParams) => Promise<{
+      sort: "VIEWS" | "ADD_TO_CARTS" | "PURCHASES" | "REVENUE" | "IMPRESSIONS";
+      rows: {
+        productId: string;
+        productName: string | null;
+        impressions: number;
+        views: number;
+        viewSessions: number;
+        addToCarts: number;
+        purchases: number;
+        quantity: number;
+        revenue: number;
+        purchaseRate: number | null;
+      }[];
+      from: string;
+      to: string;
+      timezone: "Asia/Seoul";
+      currency: "KRW";
+      includeTest: boolean;
+      lastComputedAt: string | null;
+    }>;
+    /** `GET /v1/analytics/sources` — 채널·소스·캠페인·기기별 세션과 구매 */
+    sources: (params: AnalyticsSourcesParams) => Promise<{
+      groupBy: "CHANNEL" | "SOURCE" | "CAMPAIGN" | "DEVICE";
+      rows: {
+        channel: "PAID" | "DIRECT" | "CAMPAIGN" | "ORGANIC_SEARCH" | "SOCIAL" | "EMAIL" | "REFERRAL" | "UNKNOWN" | null;
+        source: string | null;
+        medium: string | null;
+        campaign: string | null;
+        device: "unknown" | "desktop" | "mobile" | "tablet" | null;
+        sessions: number;
+        visitors: number;
+        engagedSessions: number;
+        purchaseSessions: number;
+        purchases: number;
+        revenue: number;
+        conversionRate: number | null;
+      }[];
+      from: string;
+      to: string;
+      timezone: "Asia/Seoul";
+      currency: "KRW";
+      includeTest: boolean;
+      lastComputedAt: string | null;
+    }>;
+  };
   /**
    * 결제 내역 — 스코프 `settlement:r`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
    * 결제(카드 거절·결제창 이탈·승인 결과 확인 중)도 그대로 나온다.
@@ -5438,7 +5802,7 @@ export declare const scopeAccessSchema: z.ZodEnum<{
   rw: "rw";
 }>;
 export type ScopeAccess = z.infer<typeof scopeAccessSchema>;
-/** 리소스별로 부여 가능한 접근 수준. settlement는 쓰기 API가 없어 `r`만 존재한다 */
+/** 리소스별로 부여 가능한 접근 수준. settlement·analytics는 쓰기 API가 없어 `r`만 존재한다 */
 export declare const STORE_SCOPE_RESOURCES: {
   readonly product: readonly ["r", "rw"];
   readonly category: readonly ["r", "rw"];
@@ -5447,6 +5811,7 @@ export declare const STORE_SCOPE_RESOURCES: {
   readonly inquiry: readonly ["r", "rw"];
   readonly review: readonly ["r", "rw"];
   readonly settlement: readonly ["r"];
+  readonly analytics: readonly ["r"];
   readonly webhook: readonly ["r", "rw"];
   readonly store: readonly ["r", "rw"];
   readonly member: readonly ["r", "rw"];
@@ -5460,6 +5825,7 @@ export declare const storeScopeResourceSchema: z.ZodEnum<{
   inquiry: "inquiry";
   review: "review";
   settlement: "settlement";
+  analytics: "analytics";
   webhook: "webhook";
   store: "store";
   member: "member";
@@ -5472,8 +5838,8 @@ export declare function isStoreScope(scope: string): boolean;
  * 발급 시 지정한 스코프만 갖는다(발급자 보유 스코프 이내).
  */
 export declare const STORE_ROLE_SCOPES: {
-  readonly OWNER: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "settlement:r", "webhook:rw", "store:rw", "member:rw"];
-  readonly ADMIN: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "webhook:rw", "store:rw", "member:rw"];
+  readonly OWNER: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "settlement:r", "analytics:r", "webhook:rw", "store:rw", "member:rw"];
+  readonly ADMIN: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "analytics:r", "webhook:rw", "store:rw", "member:rw"];
   readonly STAFF: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw"];
 };
 //#endregion

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).
@@ -1927,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`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
 		* 결제(카드 거절·결제창 이탈·승인 결과 확인 중)도 그대로 나온다.
@@ -2162,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"],
@@ -2171,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"]
@@ -2196,6 +2340,7 @@ const STORE_ROLE_SCOPES = {
 		"inquiry:rw",
 		"review:rw",
 		"settlement:r",
+		"analytics:r",
 		"webhook:rw",
 		"store:rw",
 		"member:rw"
@@ -2207,6 +2352,7 @@ const STORE_ROLE_SCOPES = {
 		"claim:rw",
 		"inquiry:rw",
 		"review:rw",
+		"analytics:r",
 		"webhook:rw",
 		"store:rw",
 		"member:rw"
@@ -2448,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, addressChangeRequestListSchema, addressTypeSchema, 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 };
+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.1",
+  "version": "0.2.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -1,6 +1,17 @@
 import { z } from "zod";
 import { base64Utf8 } from "./base64";
 import { createHttp, path, type Query, resolveToken, type TokenSource, unwrapData } from "./http";
+import {
+  type AnalyticsProductsParams,
+  type AnalyticsRangeParams,
+  type AnalyticsSourcesParams,
+  analyticsOverviewSchema,
+  analyticsProductsQuerySchema,
+  analyticsProductsSchema,
+  analyticsRangeQuerySchema,
+  analyticsSourcesQuerySchema,
+  analyticsSourcesSchema,
+} from "./schemas/analytics";
 import {
   type ApiClientListParams,
   apiClientSchema,
@@ -606,6 +617,29 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
     },
 
+    /**
+     * 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+     * 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
+     * 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
+     */
+    analytics: {
+      /** `GET /v1/analytics/overview` — 합계·세션 퍼널·날짜별 값 */
+      overview: (params: AnalyticsRangeParams) =>
+        storeHttp.request("GET", "/analytics/overview", analyticsOverviewSchema, {
+          query: analyticsRangeQuerySchema.parse(params),
+        }),
+      /** `GET /v1/analytics/products` — 상품별 노출·조회·장바구니·구매 */
+      products: (params: AnalyticsProductsParams) =>
+        storeHttp.request("GET", "/analytics/products", analyticsProductsSchema, {
+          query: analyticsProductsQuerySchema.parse(params) as unknown as Query,
+        }),
+      /** `GET /v1/analytics/sources` — 채널·소스·캠페인·기기별 세션과 구매 */
+      sources: (params: AnalyticsSourcesParams) =>
+        storeHttp.request("GET", "/analytics/sources", analyticsSourcesSchema, {
+          query: analyticsSourcesQuerySchema.parse(params),
+        }),
+    },
+
     /**
      * 결제 내역 — 스코프 `settlement:r`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
      * 결제(카드 거절·결제창 이탈·승인 결과 확인 중)도 그대로 나온다.

package/src/index.ts

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

package/src/schemas/analytics.ts

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

package/src/schemas/scope.ts

@@ -14,7 +14,7 @@ export const scopeAccessSchema = z
   .describe("접근 수준. `r`=읽기, `rw`=읽기+쓰기(r을 함의)");
 export type ScopeAccess = z.infer<typeof scopeAccessSchema>;
 
-/** 리소스별로 부여 가능한 접근 수준. settlement는 쓰기 API가 없어 `r`만 존재한다 */
+/** 리소스별로 부여 가능한 접근 수준. settlement·analytics는 쓰기 API가 없어 `r`만 존재한다 */
 export const STORE_SCOPE_RESOURCES = {
   product: ["r", "rw"],
   category: ["r", "rw"],
@@ -23,6 +23,7 @@ export const STORE_SCOPE_RESOURCES = {
   inquiry: ["r", "rw"],
   review: ["r", "rw"],
   settlement: ["r"],
+  analytics: ["r"],
   webhook: ["r", "rw"],
   store: ["r", "rw"],
   member: ["r", "rw"],
@@ -56,6 +57,7 @@ export const STORE_ROLE_SCOPES = {
     "inquiry:rw",
     "review:rw",
     "settlement:r",
+    "analytics:r",
     "webhook:rw",
     "store:rw",
     "member:rw",
@@ -67,6 +69,7 @@ export const STORE_ROLE_SCOPES = {
     "claim:rw",
     "inquiry:rw",
     "review:rw",
+    "analytics:r",
     "webhook:rw",
     "store:rw",
     "member:rw",