@sayren/store-sdk 0.5.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
 /**
@@ -976,11 +1132,14 @@ export declare const claimSchema: z.ZodObject<{
   }, z.core.$strip>>;
   requestedAt: z.ZodString;
   completedAt: z.ZodNullable<z.ZodString>;
+  holdExpiresAt: z.ZodNullable<z.ZodString>;
+  holdUsed: z.ZodBoolean;
 }, z.core.$strip>;
 export type Claim = z.infer<typeof claimSchema>;
 export interface ClaimListParams extends PageParams {
   type?: ClaimType;
-  status?: ClaimStatus;
+  /** 여러 상태를 한 번에 거를 수 있다(처리 대기 목록 등) */
+  status?: ClaimStatus | ClaimStatus[];
   orderItemId?: string;
   requestedFrom?: string;
   requestedTo?: string;
@@ -994,17 +1153,7 @@ export declare const claimListQuerySchema: z.ZodObject<{
     EXCHANGE: "EXCHANGE";
     CANCEL: "CANCEL";
   }>>;
-  status: z.ZodOptional<z.ZodEnum<{
-    REQUESTED: "REQUESTED";
-    HELD: "HELD";
-    COLLECTING: "COLLECTING";
-    COLLECTED: "COLLECTED";
-    REDELIVERING: "REDELIVERING";
-    APPROVED: "APPROVED";
-    REJECTED: "REJECTED";
-    COMPLETED: "COMPLETED";
-    WITHDRAWN: "WITHDRAWN";
-  }>>;
+  status: z.ZodOptional<z.ZodString>;
   orderItemId: z.ZodOptional<z.ZodString>;
   requestedFrom: z.ZodOptional<z.ZodString>;
   requestedTo: z.ZodOptional<z.ZodString>;
@@ -1061,6 +1210,8 @@ export declare const claimDetailSchema: z.ZodObject<{
   }, z.core.$strip>>;
   requestedAt: z.ZodString;
   completedAt: z.ZodNullable<z.ZodString>;
+  holdExpiresAt: z.ZodNullable<z.ZodString>;
+  holdUsed: z.ZodBoolean;
   histories: z.ZodOptional<z.ZodArray<z.ZodObject<{
     status: z.ZodEnum<{
       REQUESTED: "REQUESTED";
@@ -1245,7 +1396,7 @@ export declare const withdrawCustomerRequestSchema: z.ZodObject<{
   memo: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type WithdrawCustomerRequest = z.infer<typeof withdrawCustomerRequestSchema>;
-/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프론트 탈퇴와 같다) */
 export declare const customerWithdrawalBlockedDetailsSchema: z.ZodObject<{
   inProgressOrderItems: z.ZodNumber;
   openClaims: z.ZodNumber;
@@ -3542,7 +3693,7 @@ export declare function isReservedStoreCode(code: string): boolean;
 export declare const storeCodeSchema: z.ZodString;
 /** `https://shop.example.com`처럼 경로·쿼리 없는 http(s) 오리진인가 */
 export declare function isWebOrigin(value: string): boolean;
-/** 방문 분석을 보낼 수 있는 스토어프런트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
+/** 방문 분석을 보낼 수 있는 스토어프론트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
 export declare const analyticsOriginSchema: z.ZodString;
 /** 허용 오리진 상한 */
 export declare const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
@@ -4589,6 +4740,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
         } | null;
         requestedAt: string;
         completedAt: string | null;
+        holdExpiresAt: string | null;
+        holdUsed: boolean;
       }[];
     }>;
     get: (claimId: string) => Promise<{
@@ -4615,6 +4768,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
       } | null;
       requestedAt: string;
       completedAt: string | null;
+      holdExpiresAt: string | null;
+      holdUsed: boolean;
       histories?: {
         status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
         actor: "BUYER" | "SELLER" | "SYSTEM";
@@ -4639,6 +4794,34 @@ export declare function createStoreClient(options: StoreClientOptions): {
       holdExpiresAt: string;
     }>;
     releaseHold: (claimId: string) => Promise<void>;
+    /** 교환 완료 — 재배송 중인 교환을 셀러가 명시적으로 끝낸다 */
+    completeExchange: (claimId: string) => Promise<{
+      claimId: string;
+      type: "RETURN" | "EXCHANGE" | "CANCEL";
+      status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
+      orderId: string;
+      orderItemId: string;
+      productName: string;
+      quantity: number;
+      reason: "CHANGE_OF_MIND" | "WRONG_ORDER" | "DEFECTIVE" | "WRONG_DELIVERY" | "DIFFERENT_FROM_PAGE" | "DELAY";
+      reasonDetail: string | null;
+      responsibility: "BUYER" | "SELLER";
+      claimDeliveryFee: number;
+      expectedRefundAmount: number | null;
+      exchangeOption: {
+        optionId: string;
+        optionName: string;
+      } | null;
+      collect: {
+        method: "SELLER_PICKUP" | "BUYER_SEND";
+        carrierCode: string | null;
+        trackingNumber: string | null;
+      } | null;
+      requestedAt: string;
+      completedAt: string | null;
+      holdExpiresAt: string | null;
+      holdUsed: boolean;
+    }>;
   };
   inquiries: {
     list: (params?: PageParams & {
@@ -4993,7 +5176,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
     }>;
   };
   /**
-   * 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+   * 방문 분석 — 스코프 `analytics:r`. 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
    * 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
    * 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
    */
@@ -5038,6 +5221,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         conversionRate: number | null;
         date: string;
       }[];
+      excludedBotSessions: number;
       from: string;
       to: string;
       timezone: "Asia/Seoul";
@@ -5059,6 +5243,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         quantity: number;
         revenue: number;
         purchaseRate: number | null;
+        clickThroughRate: number | null;
       }[];
       from: string;
       to: string;
@@ -5091,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`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
@@ -6124,7 +6404,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
     }>;
     /**
      * `PATCH /v1/store` — 스코프 `store:rw`. 바꿀 필드만 보낸다. `analyticsAllowedOrigins`는 방문 분석 수집을 받을
-     * 스토어프런트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
+     * 스토어프론트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
      */
     update: (body: UpdateStoreRequest) => Promise<{
       storeId: string;