@sayren/store-sdk 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -1108,6 +1108,145 @@ export declare const approveClaimResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ApproveClaimResult = z.infer<typeof approveClaimResultSchema>;
 //#endregion
+//#region src/schemas/customer.d.ts
+/** 구매자 목록 정렬 */
+export declare const customerSortSchema: z.ZodEnum<{
+  joined_desc: "joined_desc";
+  joined_asc: "joined_asc";
+  total_paid_desc: "total_paid_desc";
+  order_count_desc: "order_count_desc";
+  last_ordered_desc: "last_ordered_desc";
+}>;
+export type CustomerSort = z.infer<typeof customerSortSchema>;
+/** `GET /v1/customers` 쿼리 */
+export declare const customerListQuerySchema: z.ZodObject<{
+  page: z.ZodOptional<z.ZodString>;
+  size: z.ZodOptional<z.ZodString>;
+  q: z.ZodOptional<z.ZodString>;
+  joinedFrom: z.ZodOptional<z.ZodString>;
+  joinedTo: z.ZodOptional<z.ZodString>;
+  marketing: z.ZodOptional<z.ZodEnum<{
+    agreed: "agreed";
+    declined: "declined";
+  }>>;
+  sort: z.ZodOptional<z.ZodEnum<{
+    joined_desc: "joined_desc";
+    joined_asc: "joined_asc";
+    total_paid_desc: "total_paid_desc";
+    order_count_desc: "order_count_desc";
+    last_ordered_desc: "last_ordered_desc";
+  }>>;
+}, z.core.$strip>;
+/** 구매 통계 — 구매 금액은 취소된 주문 상품을 빼고, 완료된 반품은 수량 비율로 뺀 금액이다 */
+export declare const customerStatsSchema: z.ZodObject<{
+  orderCount: z.ZodNumber;
+  totalPaid: z.ZodNumber;
+  lastOrderedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** 목록 행 — 휴대폰은 가운데를 가린다(`010-****-1234`) */
+export declare const customerSummarySchema: z.ZodObject<{
+  customerId: z.ZodString;
+  name: z.ZodString;
+  email: z.ZodString;
+  maskedPhone: z.ZodNullable<z.ZodString>;
+  joinedAt: z.ZodString;
+  point: z.ZodNumber;
+  marketingAgreed: z.ZodBoolean;
+  orderCount: z.ZodNumber;
+  totalPaid: z.ZodNumber;
+  lastOrderedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CustomerSummary = z.infer<typeof customerSummarySchema>;
+export declare const customerAddressSchema: z.ZodObject<{
+  addressId: z.ZodString;
+  alias: z.ZodString;
+  isDefault: z.ZodBoolean;
+  receiverName: z.ZodString;
+  phone: z.ZodString;
+  zipCode: z.ZodString;
+  address1: z.ZodString;
+  address2: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** 구매자 상세 — 휴대폰 전체를 보여 준다 */
+export declare const customerDetailSchema: z.ZodObject<{
+  customerId: z.ZodString;
+  name: z.ZodString;
+  email: z.ZodString;
+  phone: z.ZodNullable<z.ZodString>;
+  joinedAt: z.ZodString;
+  point: z.ZodNumber;
+  marketingAgreed: z.ZodBoolean;
+  loginMethods: z.ZodArray<z.ZodEnum<{
+    password: "password";
+  }>>;
+  addresses: z.ZodArray<z.ZodObject<{
+    addressId: z.ZodString;
+    alias: z.ZodString;
+    isDefault: z.ZodBoolean;
+    receiverName: z.ZodString;
+    phone: z.ZodString;
+    zipCode: z.ZodString;
+    address1: z.ZodString;
+    address2: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+  stats: z.ZodObject<{
+    orderCount: z.ZodNumber;
+    totalPaid: z.ZodNumber;
+    lastOrderedAt: z.ZodNullable<z.ZodString>;
+    canceledOrReturnedCount: z.ZodNumber;
+    reviewCount: z.ZodNumber;
+    inquiryCount: z.ZodNumber;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+export type CustomerDetail = z.infer<typeof customerDetailSchema>;
+/** 구매자의 주문 — 전체 기간 */
+export declare const customerOrderSchema: z.ZodObject<{
+  orderId: z.ZodString;
+  orderedAt: z.ZodString;
+  totalAmount: z.ZodNumber;
+  testPayment: z.ZodBoolean;
+  items: z.ZodArray<z.ZodObject<{
+    orderItemId: z.ZodString;
+    productName: z.ZodString;
+    optionName: z.ZodNullable<z.ZodString>;
+    quantity: z.ZodNumber;
+    status: z.ZodEnum<{
+      PAID: "PAID";
+      PAYMENT_WAITING: "PAYMENT_WAITING";
+      CONFIRMED: "CONFIRMED";
+      DISPATCHED: "DISPATCHED";
+      DELIVERING: "DELIVERING";
+      DELIVERED: "DELIVERED";
+      PURCHASE_DECIDED: "PURCHASE_DECIDED";
+      CANCELED: "CANCELED";
+    }>;
+    claimStatus: z.ZodNullable<z.ZodEnum<{
+      CANCEL_REQUESTED: "CANCEL_REQUESTED";
+      RETURN_REQUESTED: "RETURN_REQUESTED";
+      EXCHANGE_REQUESTED: "EXCHANGE_REQUESTED";
+    }>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CustomerOrder = z.infer<typeof customerOrderSchema>;
+/** `POST /v1/customers/{id}/withdraw` 본문 */
+export declare const withdrawCustomerRequestSchema: z.ZodObject<{
+  reason: z.ZodEnum<{
+    BUYER_REQUEST: "BUYER_REQUEST";
+    DORMANT: "DORMANT";
+    ABUSE: "ABUSE";
+    OTHER: "OTHER";
+  }>;
+  memo: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WithdrawCustomerRequest = z.infer<typeof withdrawCustomerRequestSchema>;
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+export declare const customerWithdrawalBlockedDetailsSchema: z.ZodObject<{
+  inProgressOrderItems: z.ZodNumber;
+  openClaims: z.ZodNumber;
+  pendingPayments: z.ZodNumber;
+}, z.core.$strip>;
+export type CustomerWithdrawalBlockedDetails = z.infer<typeof customerWithdrawalBlockedDetailsSchema>;
+//#endregion
 //#region src/schemas/misc.d.ts
 export declare const inquirySchema: z.ZodObject<{
   inquiryId: z.ZodString;
@@ -3333,6 +3472,7 @@ export declare const updateStoreRequestSchema: z.ZodObject<{
   customerCenterPhone: z.ZodOptional<z.ZodString>;
   businessHours: z.ZodOptional<z.ZodString>;
   analyticsAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  guestCheckoutEnabled: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type UpdateStoreRequest = z.infer<typeof updateStoreRequestSchema>;
 export declare const storeSchema: z.ZodObject<{
@@ -3349,6 +3489,7 @@ export declare const storeSchema: z.ZodObject<{
   businessNumber: z.ZodNullable<z.ZodString>;
   customerCenterPhone: z.ZodNullable<z.ZodString>;
   analyticsAllowedOrigins: z.ZodArray<z.ZodString>;
+  guestCheckoutEnabled: z.ZodBoolean;
   memberCount: z.ZodNumber;
   createdAt: z.ZodString;
 }, z.core.$strip>;
@@ -4464,6 +4605,76 @@ export declare function createStoreClient(options: StoreClientOptions): {
     answer: (inquiryId: string, content: string) => Promise<void>;
     updateAnswer: (inquiryId: string, content: string) => Promise<void>;
   };
+  /** 구매자 관리 — 조회 `customer:r`, 탈퇴 처리 `customer:rw`(콘솔 OWNER·ADMIN) */
+  customers: {
+    list: (params?: PageParams & Omit<z.input<typeof customerListQuerySchema>, "page" | "size">) => Promise<{
+      page: number;
+      size: number;
+      totalElements: number;
+      totalPages: number;
+      contents: {
+        customerId: string;
+        name: string;
+        email: string;
+        maskedPhone: string | null;
+        joinedAt: string;
+        point: number;
+        marketingAgreed: boolean;
+        orderCount: number;
+        totalPaid: number;
+        lastOrderedAt: string | null;
+      }[];
+    }>;
+    get: (customerId: string) => Promise<{
+      customerId: string;
+      name: string;
+      email: string;
+      phone: string | null;
+      joinedAt: string;
+      point: number;
+      marketingAgreed: boolean;
+      loginMethods: "password"[];
+      addresses: {
+        addressId: string;
+        alias: string;
+        isDefault: boolean;
+        receiverName: string;
+        phone: string;
+        zipCode: string;
+        address1: string;
+        address2: string | null;
+      }[];
+      stats: {
+        orderCount: number;
+        totalPaid: number;
+        lastOrderedAt: string | null;
+        canceledOrReturnedCount: number;
+        reviewCount: number;
+        inquiryCount: number;
+      };
+    }>;
+    orders: (customerId: string, params?: PageParams) => Promise<{
+      page: number;
+      size: number;
+      totalElements: number;
+      totalPages: number;
+      contents: {
+        orderId: string;
+        orderedAt: string;
+        totalAmount: number;
+        testPayment: boolean;
+        items: {
+          orderItemId: string;
+          productName: string;
+          optionName: string | null;
+          quantity: number;
+          status: "PAID" | "PAYMENT_WAITING" | "CONFIRMED" | "DISPATCHED" | "DELIVERING" | "DELIVERED" | "PURCHASE_DECIDED" | "CANCELED";
+          claimStatus: "CANCEL_REQUESTED" | "RETURN_REQUESTED" | "EXCHANGE_REQUESTED" | null;
+        }[];
+      }[];
+    }>;
+    withdraw: (customerId: string, body: WithdrawCustomerRequest) => Promise<void>;
+  };
   customerInquiries: {
     list: (params?: PageParams & {
       answered?: boolean;
@@ -5723,6 +5934,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       businessNumber: string | null;
       customerCenterPhone: string | null;
       analyticsAllowedOrigins: string[];
+      guestCheckoutEnabled: boolean;
       memberCount: number;
       createdAt: string;
     }>;
@@ -5740,6 +5952,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       businessNumber: string | null;
       customerCenterPhone: string | null;
       analyticsAllowedOrigins: string[];
+      guestCheckoutEnabled: boolean;
       memberCount: number;
       createdAt: string;
     }>;
@@ -5849,6 +6062,7 @@ export declare const STORE_SCOPE_RESOURCES: {
   readonly webhook: readonly ["r", "rw"];
   readonly store: readonly ["r", "rw"];
   readonly member: readonly ["r", "rw"];
+  readonly customer: readonly ["r", "rw"];
 };
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
 export declare const storeScopeResourceSchema: z.ZodEnum<{
@@ -5863,6 +6077,7 @@ export declare const storeScopeResourceSchema: z.ZodEnum<{
   webhook: "webhook";
   store: "store";
   member: "member";
+  customer: "customer";
 }>;
 /** 카탈로그상 존재하는 스코프 문자열인가 (예: `settlement:rw`는 false) */
 export declare function isStoreScope(scope: string): boolean;
@@ -5872,9 +6087,9 @@ 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", "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"];
+  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", "customer:rw"];
+  readonly ADMIN: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "analytics:r", "webhook:rw", "store:rw", "member:rw", "customer:rw"];
+  readonly STAFF: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "customer:r"];
 };
 //#endregion
 //#region src/schemas/webhook-event.d.ts

package/dist/index.mjs

@@ -698,6 +698,103 @@ const approveClaimResultSchema = z.object({
 	refundedAt: z.string()
 });
 //#endregion
+//#region src/schemas/customer.ts
+/** 구매자 목록 정렬 */
+const customerSortSchema = z.enum([
+	"joined_desc",
+	"joined_asc",
+	"total_paid_desc",
+	"order_count_desc",
+	"last_ordered_desc"
+]).describe("정렬. `joined_desc`(기본, 최근 가입순)·`joined_asc`·`total_paid_desc`(구매 금액순)·`order_count_desc`(주문 수순)·`last_ordered_desc`(최근 주문순)");
+/** `GET /v1/customers` 쿼리 */
+const customerListQuerySchema = z.object({
+	q: z.string().optional().describe("검색어 — 이름·이메일(포함). 숫자 4자리면 휴대폰 뒤 4자리로도 찾는다"),
+	joinedFrom: z.string().optional().describe("가입일 시작(YYYY-MM-DD, KST, 포함)"),
+	joinedTo: z.string().optional().describe("가입일 끝(YYYY-MM-DD, KST, 포함)"),
+	marketing: z.enum(["agreed", "declined"]).optional().describe("마케팅 수신 동의 필터. 생략하면 전체"),
+	sort: customerSortSchema.optional(),
+	...pageQueryShape()
+});
+/** 구매 통계 — 구매 금액은 취소된 주문 상품을 빼고, 완료된 반품은 수량 비율로 뺀 금액이다 */
+const customerStatsSchema = z.object({
+	orderCount: z.number().int().describe("주문 수(취소 포함)"),
+	totalPaid: z.number().int().describe("구매 금액(원) — 취소·완료된 반품 제외"),
+	lastOrderedAt: z.string().nullable().describe("최근 주문 시각")
+});
+/** 목록 행 — 휴대폰은 가운데를 가린다(`010-****-1234`) */
+const customerSummarySchema = z.object({
+	customerId: z.string(),
+	name: z.string(),
+	email: z.string(),
+	maskedPhone: z.string().nullable(),
+	joinedAt: z.string(),
+	point: z.number().int(),
+	marketingAgreed: z.boolean()
+}).extend(customerStatsSchema.shape);
+const customerAddressSchema = z.object({
+	addressId: z.string(),
+	alias: z.string(),
+	isDefault: z.boolean(),
+	receiverName: z.string(),
+	phone: z.string(),
+	zipCode: z.string(),
+	address1: z.string(),
+	address2: z.string().nullable()
+});
+/** 구매자 상세 — 휴대폰 전체를 보여 준다 */
+const customerDetailSchema = z.object({
+	customerId: z.string(),
+	name: z.string(),
+	email: z.string(),
+	phone: z.string().nullable(),
+	joinedAt: z.string(),
+	point: z.number().int(),
+	marketingAgreed: z.boolean(),
+	loginMethods: z.array(z.enum(["password"])).describe("로그인 방법. 지금은 이메일·비밀번호(`password`)뿐이다"),
+	addresses: z.array(customerAddressSchema),
+	stats: customerStatsSchema.extend({
+		canceledOrReturnedCount: z.number().int().describe("취소된 주문 상품 + 완료된 반품 수"),
+		reviewCount: z.number().int(),
+		inquiryCount: z.number().int().describe("상품 문의 + 1:1 문의")
+	})
+});
+/** 구매자의 주문 — 전체 기간 */
+const customerOrderSchema = z.object({
+	orderId: z.string(),
+	orderedAt: z.string(),
+	totalAmount: z.number().int().describe("결제 금액"),
+	testPayment: z.boolean(),
+	items: z.array(z.object({
+		orderItemId: z.string(),
+		productName: z.string(),
+		optionName: z.string().nullable(),
+		quantity: z.number().int(),
+		status: orderItemStatusSchema,
+		claimStatus: z.enum([
+			"CANCEL_REQUESTED",
+			"RETURN_REQUESTED",
+			"EXCHANGE_REQUESTED"
+		]).nullable()
+	}))
+});
+/** `POST /v1/customers/{id}/withdraw` 본문 */
+const withdrawCustomerRequestSchema = z.object({
+	reason: z.enum([
+		"BUYER_REQUEST",
+		"DORMANT",
+		"ABUSE",
+		"OTHER"
+	]).describe("처리 사유 — 구매자 요청·장기 미이용·부정 이용·기타. 감사 로그에 남는다"),
+	memo: z.string().max(200).optional().describe("사유 보충(선택)")
+});
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+const customerWithdrawalBlockedDetailsSchema = z.object({
+	inProgressOrderItems: z.number().int(),
+	openClaims: z.number().int(),
+	pendingPayments: z.number().int()
+});
+//#endregion
 //#region src/schemas/misc.ts
 const inquirySchema = z.object({
 	inquiryId: z.string(),
@@ -1729,7 +1826,8 @@ const updateStoreRequestSchema = z.object({
 	logoUrl: z.url().optional(),
 	customerCenterPhone: z.string().optional(),
 	businessHours: z.string().max(100).optional(),
-	analyticsAllowedOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("방문 분석 수집을 받을 스토어프런트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. 넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다")
+	analyticsAllowedOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("방문 분석 수집을 받을 스토어프런트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. 넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다"),
+	guestCheckoutEnabled: z.boolean().optional().describe("비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. 장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다")
 }).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
 const storeSchema = z.object({
 	storeId: z.string(),
@@ -1745,6 +1843,7 @@ const storeSchema = z.object({
 	businessNumber: z.string().nullable(),
 	customerCenterPhone: z.string().nullable(),
 	analyticsAllowedOrigins: z.array(z.string()).describe("방문 분석 수집을 받는 스토어프런트 오리진. 비어 있으면 모든 오리진에서 받는다"),
+	guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
 	memberCount: z.number().int(),
 	createdAt: z.string()
 });
@@ -2052,6 +2151,13 @@ function createStoreClient(options) {
 			answer: (inquiryId, content) => storeHttp.requestVoid("POST", path`/inquiries/${inquiryId}/answer`, { body: { content } }),
 			updateAnswer: (inquiryId, content) => storeHttp.requestVoid("PUT", path`/inquiries/${inquiryId}/answer`, { body: { content } })
 		},
+		/** 구매자 관리 — 조회 `customer:r`, 탈퇴 처리 `customer:rw`(콘솔 OWNER·ADMIN) */
+		customers: {
+			list: (params) => storeHttp.request("GET", "/customers", pageSchema(customerSummarySchema), { query: params }),
+			get: (customerId) => storeHttp.request("GET", path`/customers/${customerId}`, customerDetailSchema),
+			orders: (customerId, params) => storeHttp.request("GET", path`/customers/${customerId}/orders`, pageSchema(customerOrderSchema), { query: params }),
+			withdraw: (customerId, body) => storeHttp.requestVoid("POST", path`/customers/${customerId}/withdraw`, { body: withdrawCustomerRequestSchema.parse(body) })
+		},
 		customerInquiries: {
 			list: (params) => storeHttp.request("GET", "/customer-inquiries", pageSchema(sellerCustomerInquirySchema), { query: params }),
 			get: (inquiryId) => storeHttp.request("GET", path`/customer-inquiries/${inquiryId}`, sellerCustomerInquirySchema),
@@ -2344,7 +2450,8 @@ const STORE_SCOPE_RESOURCES = {
 	analytics: ["r"],
 	webhook: ["r", "rw"],
 	store: ["r", "rw"],
-	member: ["r", "rw"]
+	member: ["r", "rw"],
+	customer: ["r", "rw"]
 };
 const storeScopeResourceSchema = z.enum(Object.keys(STORE_SCOPE_RESOURCES)).describe("스코프 리소스");
 /** 카탈로그상 존재하는 스코프 문자열인가 (예: `settlement:rw`는 false) */
@@ -2370,7 +2477,8 @@ const STORE_ROLE_SCOPES = {
 		"analytics:r",
 		"webhook:rw",
 		"store:rw",
-		"member:rw"
+		"member:rw",
+		"customer:rw"
 	],
 	ADMIN: [
 		"product:rw",
@@ -2382,7 +2490,8 @@ const STORE_ROLE_SCOPES = {
 		"analytics:r",
 		"webhook:rw",
 		"store:rw",
-		"member:rw"
+		"member:rw",
+		"customer:rw"
 	],
 	STAFF: [
 		"product:rw",
@@ -2390,7 +2499,8 @@ const STORE_ROLE_SCOPES = {
 		"order:rw",
 		"claim:rw",
 		"inquiry:rw",
-		"review:rw"
+		"review:rw",
+		"customer:r"
 	]
 };
 //#endregion
@@ -2621,4 +2731,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, customerInquiryCategorySchema, customerInquiryListQuerySchema, 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, 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, updateStoreRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema };
+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, 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, updateStoreRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema };

package/package.json

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

package/src/client.ts

@@ -52,6 +52,14 @@ import {
   rejectClaimRequestSchema,
 } from "./schemas/claim";
 import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
+import {
+  customerDetailSchema,
+  type customerListQuerySchema,
+  customerOrderSchema,
+  customerSummarySchema,
+  type WithdrawCustomerRequest,
+  withdrawCustomerRequestSchema,
+} from "./schemas/customer";
 import {
   type CustomerInquiryCategory,
   inquirySchema,
@@ -559,6 +567,31 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("PUT", path`/inquiries/${inquiryId}/answer`, { body: { content } }),
     },
 
+    /** 구매자 관리 — 조회 `customer:r`, 탈퇴 처리 `customer:rw`(콘솔 OWNER·ADMIN) */
+    customers: {
+      list: (
+        params?: PageParams & Omit<z.input<typeof customerListQuerySchema>, "page" | "size">,
+      ) =>
+        storeHttp.request("GET", "/customers", pageSchema(customerSummarySchema), {
+          query: params as Query,
+        }),
+      get: (customerId: string) =>
+        storeHttp.request("GET", path`/customers/${customerId}`, customerDetailSchema),
+      orders: (customerId: string, params?: PageParams) =>
+        storeHttp.request(
+          "GET",
+          path`/customers/${customerId}/orders`,
+          pageSchema(customerOrderSchema),
+          {
+            query: params as Query,
+          },
+        ),
+      withdraw: (customerId: string, body: WithdrawCustomerRequest) =>
+        storeHttp.requestVoid("POST", path`/customers/${customerId}/withdraw`, {
+          body: withdrawCustomerRequestSchema.parse(body),
+        }),
+    },
+
     customerInquiries: {
       list: (
         params?: PageParams & {

package/src/index.ts

@@ -18,6 +18,7 @@ export * from "./schemas/auth";
 export * from "./schemas/category";
 export * from "./schemas/claim";
 export * from "./schemas/common";
+export * from "./schemas/customer";
 export * from "./schemas/misc";
 export * from "./schemas/order";
 export * from "./schemas/payment";

package/src/schemas/customer.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { orderItemStatusSchema, pageQueryShape } from "./common";
+
+/** 구매자 목록 정렬 */
+export const customerSortSchema = z
+  .enum(["joined_desc", "joined_asc", "total_paid_desc", "order_count_desc", "last_ordered_desc"])
+  .describe(
+    "정렬. `joined_desc`(기본, 최근 가입순)·`joined_asc`·`total_paid_desc`(구매 금액순)·`order_count_desc`(주문 수순)·`last_ordered_desc`(최근 주문순)",
+  );
+export type CustomerSort = z.infer<typeof customerSortSchema>;
+
+/** `GET /v1/customers` 쿼리 */
+export const customerListQuerySchema = z.object({
+  q: z
+    .string()
+    .optional()
+    .describe("검색어 — 이름·이메일(포함). 숫자 4자리면 휴대폰 뒤 4자리로도 찾는다"),
+  joinedFrom: z.string().optional().describe("가입일 시작(YYYY-MM-DD, KST, 포함)"),
+  joinedTo: z.string().optional().describe("가입일 끝(YYYY-MM-DD, KST, 포함)"),
+  marketing: z
+    .enum(["agreed", "declined"])
+    .optional()
+    .describe("마케팅 수신 동의 필터. 생략하면 전체"),
+  sort: customerSortSchema.optional(),
+  ...pageQueryShape(),
+});
+
+/** 구매 통계 — 구매 금액은 취소된 주문 상품을 빼고, 완료된 반품은 수량 비율로 뺀 금액이다 */
+export const customerStatsSchema = z.object({
+  orderCount: z.number().int().describe("주문 수(취소 포함)"),
+  totalPaid: z.number().int().describe("구매 금액(원) — 취소·완료된 반품 제외"),
+  lastOrderedAt: z.string().nullable().describe("최근 주문 시각"),
+});
+
+/** 목록 행 — 휴대폰은 가운데를 가린다(`010-****-1234`) */
+export const customerSummarySchema = z
+  .object({
+    customerId: z.string(),
+    name: z.string(),
+    email: z.string(),
+    maskedPhone: z.string().nullable(),
+    joinedAt: z.string(),
+    point: z.number().int(),
+    marketingAgreed: z.boolean(),
+  })
+  .extend(customerStatsSchema.shape);
+export type CustomerSummary = z.infer<typeof customerSummarySchema>;
+
+export const customerAddressSchema = z.object({
+  addressId: z.string(),
+  alias: z.string(),
+  isDefault: z.boolean(),
+  receiverName: z.string(),
+  phone: z.string(),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullable(),
+});
+
+/** 구매자 상세 — 휴대폰 전체를 보여 준다 */
+export const customerDetailSchema = z.object({
+  customerId: z.string(),
+  name: z.string(),
+  email: z.string(),
+  phone: z.string().nullable(),
+  joinedAt: z.string(),
+  point: z.number().int(),
+  marketingAgreed: z.boolean(),
+  loginMethods: z
+    .array(z.enum(["password"]))
+    .describe("로그인 방법. 지금은 이메일·비밀번호(`password`)뿐이다"),
+  addresses: z.array(customerAddressSchema),
+  stats: customerStatsSchema.extend({
+    canceledOrReturnedCount: z.number().int().describe("취소된 주문 상품 + 완료된 반품 수"),
+    reviewCount: z.number().int(),
+    inquiryCount: z.number().int().describe("상품 문의 + 1:1 문의"),
+  }),
+});
+export type CustomerDetail = z.infer<typeof customerDetailSchema>;
+
+/** 구매자의 주문 — 전체 기간 */
+export const customerOrderSchema = z.object({
+  orderId: z.string(),
+  orderedAt: z.string(),
+  totalAmount: z.number().int().describe("결제 금액"),
+  testPayment: z.boolean(),
+  items: z.array(
+    z.object({
+      orderItemId: z.string(),
+      productName: z.string(),
+      optionName: z.string().nullable(),
+      quantity: z.number().int(),
+      status: orderItemStatusSchema,
+      claimStatus: z
+        .enum(["CANCEL_REQUESTED", "RETURN_REQUESTED", "EXCHANGE_REQUESTED"])
+        .nullable(),
+    }),
+  ),
+});
+export type CustomerOrder = z.infer<typeof customerOrderSchema>;
+
+/** `POST /v1/customers/{id}/withdraw` 본문 */
+export const withdrawCustomerRequestSchema = z.object({
+  reason: z
+    .enum(["BUYER_REQUEST", "DORMANT", "ABUSE", "OTHER"])
+    .describe("처리 사유 — 구매자 요청·장기 미이용·부정 이용·기타. 감사 로그에 남는다"),
+  memo: z.string().max(200).optional().describe("사유 보충(선택)"),
+});
+export type WithdrawCustomerRequest = z.infer<typeof withdrawCustomerRequestSchema>;
+
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+export const customerWithdrawalBlockedDetailsSchema = z.object({
+  inProgressOrderItems: z.number().int(),
+  openClaims: z.number().int(),
+  pendingPayments: z.number().int(),
+});
+export type CustomerWithdrawalBlockedDetails = z.infer<
+  typeof customerWithdrawalBlockedDetailsSchema
+>;

package/src/schemas/scope.ts

@@ -27,6 +27,7 @@ export const STORE_SCOPE_RESOURCES = {
   webhook: ["r", "rw"],
   store: ["r", "rw"],
   member: ["r", "rw"],
+  customer: ["r", "rw"],
 } as const satisfies Record<string, readonly ScopeAccess[]>;
 
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
@@ -61,6 +62,7 @@ export const STORE_ROLE_SCOPES = {
     "webhook:rw",
     "store:rw",
     "member:rw",
+    "customer:rw",
   ],
   ADMIN: [
     "product:rw",
@@ -73,6 +75,15 @@ export const STORE_ROLE_SCOPES = {
     "webhook:rw",
     "store:rw",
     "member:rw",
+    "customer:rw",
+  ],
+  STAFF: [
+    "product:rw",
+    "category:rw",
+    "order:rw",
+    "claim:rw",
+    "inquiry:rw",
+    "review:rw",
+    "customer:r",
   ],
-  STAFF: ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw"],
 } as const satisfies Record<StoreRole, readonly string[]>;

package/src/schemas/store.ts

@@ -117,6 +117,13 @@ export const updateStoreRequestSchema = z
         "방문 분석 수집을 받을 스토어프런트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. " +
           "넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다",
       ),
+    guestCheckoutEnabled: z
+      .boolean()
+      .optional()
+      .describe(
+        "비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. " +
+          "장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다",
+      ),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",
@@ -135,6 +142,7 @@ export const storeSchema = z.object({
   analyticsAllowedOrigins: z
     .array(z.string())
     .describe("방문 분석 수집을 받는 스토어프런트 오리진. 비어 있으면 모든 오리진에서 받는다"),
+  guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
   memberCount: z.number().int(),
   createdAt: z.string(),
 });