@sayren/store-sdk 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1108,6 +1108,226 @@ 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.ZodNullable<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.ZodNullable<z.ZodString>;
+  phone: z.ZodNullable<z.ZodString>;
+  joinedAt: z.ZodString;
+  point: z.ZodNumber;
+  marketingAgreed: z.ZodBoolean;
+  loginMethods: z.ZodArray<z.ZodObject<{
+    method: z.ZodEnum<{
+      kakao: "kakao";
+      naver: "naver";
+      google: "google";
+      password: "password";
+    }>;
+    linkedAt: z.ZodString;
+  }, z.core.$strip>>;
+  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/login.d.ts
+/** 소셜 로그인 공급자 */
+export declare const loginProviderSchema: z.ZodEnum<{
+  kakao: "kakao";
+  naver: "naver";
+  google: "google";
+}>;
+export type LoginProvider = z.infer<typeof loginProviderSchema>;
+/** 공급자 연결 상태 — 비밀 값은 앞 4자리만 */
+export declare const loginProviderStatusSchema: z.ZodObject<{
+  provider: z.ZodEnum<{
+    kakao: "kakao";
+    naver: "naver";
+    google: "google";
+  }>;
+  connected: z.ZodBoolean;
+  enabled: z.ZodBoolean;
+  clientIdPrefix: z.ZodNullable<z.ZodString>;
+  secretPrefix: z.ZodNullable<z.ZodString>;
+  lastTestedAt: z.ZodNullable<z.ZodString>;
+  lastTestOk: z.ZodNullable<z.ZodBoolean>;
+  linkedMemberCount: z.ZodNumber;
+  onlyMethodMemberCount: z.ZodNumber;
+  callbackUrl: z.ZodURL;
+}, z.core.$strip>;
+export type LoginProviderStatus = z.infer<typeof loginProviderStatusSchema>;
+/** `GET /v1/store/login-settings` */
+export declare const loginSettingsSchema: z.ZodObject<{
+  passwordLoginEnabled: z.ZodBoolean;
+  passwordOnlyMemberCount: z.ZodNumber;
+  storefrontOrigins: z.ZodArray<z.ZodString>;
+  providers: z.ZodArray<z.ZodObject<{
+    provider: z.ZodEnum<{
+      kakao: "kakao";
+      naver: "naver";
+      google: "google";
+    }>;
+    connected: z.ZodBoolean;
+    enabled: z.ZodBoolean;
+    clientIdPrefix: z.ZodNullable<z.ZodString>;
+    secretPrefix: z.ZodNullable<z.ZodString>;
+    lastTestedAt: z.ZodNullable<z.ZodString>;
+    lastTestOk: z.ZodNullable<z.ZodBoolean>;
+    linkedMemberCount: z.ZodNumber;
+    onlyMethodMemberCount: z.ZodNumber;
+    callbackUrl: z.ZodURL;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LoginSettings = z.infer<typeof loginSettingsSchema>;
+/** `PATCH /v1/store/login-settings` */
+export declare const updateLoginSettingsRequestSchema: z.ZodObject<{
+  passwordLoginEnabled: z.ZodBoolean;
+}, z.core.$strip>;
+export type UpdateLoginSettingsRequest = z.infer<typeof updateLoginSettingsRequestSchema>;
+/** `PUT /v1/store/auth-providers/{provider}` — 저장 전에 연결 테스트를 한다 */
+export declare const saveLoginProviderRequestSchema: z.ZodObject<{
+  clientId: z.ZodString;
+  clientSecret: z.ZodString;
+}, z.core.$strip>;
+export type SaveLoginProviderRequest = z.infer<typeof saveLoginProviderRequestSchema>;
+/** `PATCH /v1/store/auth-providers/{provider}` */
+export declare const updateLoginProviderRequestSchema: z.ZodObject<{
+  enabled: z.ZodBoolean;
+}, z.core.$strip>;
+/** 연결 테스트 결과 */
+export declare const loginProviderTestSchema: z.ZodObject<{
+  ok: z.ZodBoolean;
+  code: z.ZodNullable<z.ZodEnum<{
+    INVALID_CLIENT: "INVALID_CLIENT";
+    PROVIDER_UNAVAILABLE: "PROVIDER_UNAVAILABLE";
+  }>>;
+  testedAt: z.ZodString;
+}, z.core.$strip>;
+export type LoginProviderTest = z.infer<typeof loginProviderTestSchema>;
+//#endregion
 //#region src/schemas/misc.d.ts
 export declare const inquirySchema: z.ZodObject<{
   inquiryId: z.ZodString;
@@ -3333,6 +3553,8 @@ export declare const updateStoreRequestSchema: z.ZodObject<{
   customerCenterPhone: z.ZodOptional<z.ZodString>;
   businessHours: z.ZodOptional<z.ZodString>;
   analyticsAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  storefrontOrigins: 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 +3571,8 @@ export declare const storeSchema: z.ZodObject<{
   businessNumber: z.ZodNullable<z.ZodString>;
   customerCenterPhone: z.ZodNullable<z.ZodString>;
   analyticsAllowedOrigins: z.ZodArray<z.ZodString>;
+  storefrontOrigins: z.ZodArray<z.ZodString>;
+  guestCheckoutEnabled: z.ZodBoolean;
   memberCount: z.ZodNumber;
   createdAt: z.ZodString;
 }, z.core.$strip>;
@@ -4464,6 +4688,176 @@ export declare function createStoreClient(options: StoreClientOptions): {
     answer: (inquiryId: string, content: string) => Promise<void>;
     updateAnswer: (inquiryId: string, content: string) => Promise<void>;
   };
+  /**
+   * 구매자 로그인 설정 — 이메일·비밀번호 허용, 소셜 공급자 연결. 비밀 값을 다루므로 콘솔에 로그인한 OWNER만 호출할 수 있다
+   */
+  loginSettings: {
+    get: () => Promise<{
+      passwordLoginEnabled: boolean;
+      passwordOnlyMemberCount: number;
+      storefrontOrigins: string[];
+      providers: {
+        provider: "kakao" | "naver" | "google";
+        connected: boolean;
+        enabled: boolean;
+        clientIdPrefix: string | null;
+        secretPrefix: string | null;
+        lastTestedAt: string | null;
+        lastTestOk: boolean | null;
+        linkedMemberCount: number;
+        onlyMethodMemberCount: number;
+        callbackUrl: string;
+      }[];
+    }>;
+    update: (body: UpdateLoginSettingsRequest) => Promise<{
+      passwordLoginEnabled: boolean;
+      passwordOnlyMemberCount: number;
+      storefrontOrigins: string[];
+      providers: {
+        provider: "kakao" | "naver" | "google";
+        connected: boolean;
+        enabled: boolean;
+        clientIdPrefix: string | null;
+        secretPrefix: string | null;
+        lastTestedAt: string | null;
+        lastTestOk: boolean | null;
+        linkedMemberCount: number;
+        onlyMethodMemberCount: number;
+        callbackUrl: string;
+      }[];
+    }>;
+    /** 키 저장 — 저장 전에 연결 테스트를 하고, 실패하면 422 `LOGIN_PROVIDER_VERIFICATION_FAILED` */
+    saveProvider: (provider: LoginProvider, body: SaveLoginProviderRequest) => Promise<{
+      passwordLoginEnabled: boolean;
+      passwordOnlyMemberCount: number;
+      storefrontOrigins: string[];
+      providers: {
+        provider: "kakao" | "naver" | "google";
+        connected: boolean;
+        enabled: boolean;
+        clientIdPrefix: string | null;
+        secretPrefix: string | null;
+        lastTestedAt: string | null;
+        lastTestOk: boolean | null;
+        linkedMemberCount: number;
+        onlyMethodMemberCount: number;
+        callbackUrl: string;
+      }[];
+    }>;
+    setProviderEnabled: (provider: LoginProvider, enabled: boolean) => Promise<{
+      passwordLoginEnabled: boolean;
+      passwordOnlyMemberCount: number;
+      storefrontOrigins: string[];
+      providers: {
+        provider: "kakao" | "naver" | "google";
+        connected: boolean;
+        enabled: boolean;
+        clientIdPrefix: string | null;
+        secretPrefix: string | null;
+        lastTestedAt: string | null;
+        lastTestOk: boolean | null;
+        linkedMemberCount: number;
+        onlyMethodMemberCount: number;
+        callbackUrl: string;
+      }[];
+    }>;
+    testProvider: (provider: LoginProvider) => Promise<{
+      ok: boolean;
+      code: "INVALID_CLIENT" | "PROVIDER_UNAVAILABLE" | null;
+      testedAt: string;
+    }>;
+    /** 연결 해제 — 키를 지운다. 연결된 구매자 계정은 남는다 */
+    removeProvider: (provider: LoginProvider) => Promise<{
+      passwordLoginEnabled: boolean;
+      passwordOnlyMemberCount: number;
+      storefrontOrigins: string[];
+      providers: {
+        provider: "kakao" | "naver" | "google";
+        connected: boolean;
+        enabled: boolean;
+        clientIdPrefix: string | null;
+        secretPrefix: string | null;
+        lastTestedAt: string | null;
+        lastTestOk: boolean | null;
+        linkedMemberCount: number;
+        onlyMethodMemberCount: number;
+        callbackUrl: string;
+      }[];
+    }>;
+  };
+  /** 구매자 관리 — 조회 `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 | null;
+        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 | null;
+      phone: string | null;
+      joinedAt: string;
+      point: number;
+      marketingAgreed: boolean;
+      loginMethods: {
+        method: "kakao" | "naver" | "google" | "password";
+        linkedAt: string;
+      }[];
+      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 +6117,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
       businessNumber: string | null;
       customerCenterPhone: string | null;
       analyticsAllowedOrigins: string[];
+      storefrontOrigins: string[];
+      guestCheckoutEnabled: boolean;
       memberCount: number;
       createdAt: string;
     }>;
@@ -5740,6 +6136,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
       businessNumber: string | null;
       customerCenterPhone: string | null;
       analyticsAllowedOrigins: string[];
+      storefrontOrigins: string[];
+      guestCheckoutEnabled: boolean;
       memberCount: number;
       createdAt: string;
     }>;
@@ -5849,6 +6247,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 +6262,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 +6272,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,160 @@ 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(),
+	/** 소셜 가입에서 이메일을 받지 못했으면 null */
+	email: z.string().nullable(),
+	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().nullable(),
+	phone: z.string().nullable(),
+	joinedAt: z.string(),
+	point: z.number().int(),
+	marketingAgreed: z.boolean(),
+	loginMethods: z.array(z.object({
+		method: z.enum([
+			"password",
+			"kakao",
+			"naver",
+			"google"
+		]),
+		/** 소셜 연결 시각. 비밀번호는 가입 시각 */
+		linkedAt: z.string()
+	})).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/login.ts
+/** 소셜 로그인 공급자 */
+const loginProviderSchema = z.enum([
+	"kakao",
+	"naver",
+	"google"
+]);
+/** 공급자 연결 상태 — 비밀 값은 앞 4자리만 */
+const loginProviderStatusSchema = z.object({
+	provider: loginProviderSchema,
+	connected: z.boolean(),
+	/** 스토어프런트에서 사용 중인지. 연결 안 됐으면 false */
+	enabled: z.boolean(),
+	clientIdPrefix: z.string().nullable().describe("클라이언트 ID(카카오 REST API 키) 앞 4자리"),
+	secretPrefix: z.string().nullable(),
+	lastTestedAt: z.string().nullable(),
+	lastTestOk: z.boolean().nullable(),
+	linkedMemberCount: z.number().int().describe("이 공급자로 연결된 구매자 수"),
+	/** 이 공급자로만 로그인하는 구매자 수 — 연결을 해제하면 로그인할 방법이 없어진다 */
+	onlyMethodMemberCount: z.number().int(),
+	callbackUrl: z.url().describe("공급자 개발자 콘솔에 등록할 리디렉트 URI")
+});
+/** `GET /v1/store/login-settings` */
+const loginSettingsSchema = z.object({
+	passwordLoginEnabled: z.boolean(),
+	/** 비밀번호로만 로그인하는 구매자 수 — 이메일·비밀번호를 끄면 이들은 로그인할 수 없다 */
+	passwordOnlyMemberCount: z.number().int(),
+	storefrontOrigins: z.array(z.string()),
+	providers: z.array(loginProviderStatusSchema)
+});
+/** `PATCH /v1/store/login-settings` */
+const updateLoginSettingsRequestSchema = z.object({ passwordLoginEnabled: z.boolean() });
+/** `PUT /v1/store/auth-providers/{provider}` — 저장 전에 연결 테스트를 한다 */
+const saveLoginProviderRequestSchema = z.object({
+	clientId: z.string().trim().min(1).max(200),
+	clientSecret: z.string().trim().min(1).max(500)
+});
+/** `PATCH /v1/store/auth-providers/{provider}` */
+const updateLoginProviderRequestSchema = z.object({ enabled: z.boolean() });
+/** 연결 테스트 결과 */
+const loginProviderTestSchema = z.object({
+	ok: z.boolean(),
+	/** 실패 이유 — `INVALID_CLIENT`(키가 틀림)·`PROVIDER_UNAVAILABLE`(공급자 응답 없음) */
+	code: z.enum(["INVALID_CLIENT", "PROVIDER_UNAVAILABLE"]).nullable(),
+	testedAt: z.string()
+});
+//#endregion
 //#region src/schemas/misc.ts
 const inquirySchema = z.object({
 	inquiryId: z.string(),
@@ -1729,7 +1883,9 @@ 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("@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프런트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. 넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다"),
+	storefrontOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("스토어프런트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. `analyticsAllowedOrigins`와 같은 목록이다(둘 다 주면 이 값이 이긴다)"),
+	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 +1901,8 @@ const storeSchema = z.object({
 	businessNumber: z.string().nullable(),
 	customerCenterPhone: z.string().nullable(),
 	analyticsAllowedOrigins: z.array(z.string()).describe("방문 분석 수집을 받는 스토어프런트 오리진. 비어 있으면 모든 오리진에서 받는다"),
+	storefrontOrigins: z.array(z.string()).describe("스토어프런트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)"),
+	guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
 	memberCount: z.number().int(),
 	createdAt: z.string()
 });
@@ -2052,6 +2210,26 @@ 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 } })
 		},
+		/**
+		* 구매자 로그인 설정 — 이메일·비밀번호 허용, 소셜 공급자 연결. 비밀 값을 다루므로 콘솔에 로그인한 OWNER만 호출할 수 있다
+		*/
+		loginSettings: {
+			get: () => storeHttp.request("GET", "/store/login-settings", loginSettingsSchema),
+			update: (body) => storeHttp.request("PATCH", "/store/login-settings", loginSettingsSchema, { body: updateLoginSettingsRequestSchema.parse(body) }),
+			/** 키 저장 — 저장 전에 연결 테스트를 하고, 실패하면 422 `LOGIN_PROVIDER_VERIFICATION_FAILED` */
+			saveProvider: (provider, body) => storeHttp.request("PUT", path`/store/auth-providers/${provider}`, loginSettingsSchema, { body: saveLoginProviderRequestSchema.parse(body) }),
+			setProviderEnabled: (provider, enabled) => storeHttp.request("PATCH", path`/store/auth-providers/${provider}`, loginSettingsSchema, { body: { enabled } }),
+			testProvider: (provider) => storeHttp.request("POST", path`/store/auth-providers/${provider}/test`, loginProviderTestSchema),
+			/** 연결 해제 — 키를 지운다. 연결된 구매자 계정은 남는다 */
+			removeProvider: (provider) => storeHttp.request("DELETE", path`/store/auth-providers/${provider}`, loginSettingsSchema)
+		},
+		/** 구매자 관리 — 조회 `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 +2522,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 +2549,8 @@ const STORE_ROLE_SCOPES = {
 		"analytics:r",
 		"webhook:rw",
 		"store:rw",
-		"member:rw"
+		"member:rw",
+		"customer:rw"
 	],
 	ADMIN: [
 		"product:rw",
@@ -2382,7 +2562,8 @@ const STORE_ROLE_SCOPES = {
 		"analytics:r",
 		"webhook:rw",
 		"store:rw",
-		"member:rw"
+		"member:rw",
+		"customer:rw"
 	],
 	STAFF: [
 		"product:rw",
@@ -2390,7 +2571,8 @@ const STORE_ROLE_SCOPES = {
 		"order:rw",
 		"claim:rw",
 		"inquiry:rw",
-		"review:rw"
+		"review:rw",
+		"customer:r"
 	]
 };
 //#endregion
@@ -2621,4 +2803,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, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentRoutingModeSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageUploadResultSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, refreshUserToken, rejectClaimRequestSchema, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingUpdateResultSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema };

package/package.json

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

package/src/client.ts

@@ -52,6 +52,23 @@ 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 LoginProvider,
+  loginProviderTestSchema,
+  loginSettingsSchema,
+  type SaveLoginProviderRequest,
+  saveLoginProviderRequestSchema,
+  type UpdateLoginSettingsRequest,
+  updateLoginSettingsRequestSchema,
+} from "./schemas/login";
 import {
   type CustomerInquiryCategory,
   inquirySchema,
@@ -559,6 +576,60 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("PUT", path`/inquiries/${inquiryId}/answer`, { body: { content } }),
     },
 
+    /**
+     * 구매자 로그인 설정 — 이메일·비밀번호 허용, 소셜 공급자 연결. 비밀 값을 다루므로 콘솔에 로그인한 OWNER만 호출할 수 있다
+     */
+    loginSettings: {
+      get: () => storeHttp.request("GET", "/store/login-settings", loginSettingsSchema),
+      update: (body: UpdateLoginSettingsRequest) =>
+        storeHttp.request("PATCH", "/store/login-settings", loginSettingsSchema, {
+          body: updateLoginSettingsRequestSchema.parse(body),
+        }),
+      /** 키 저장 — 저장 전에 연결 테스트를 하고, 실패하면 422 `LOGIN_PROVIDER_VERIFICATION_FAILED` */
+      saveProvider: (provider: LoginProvider, body: SaveLoginProviderRequest) =>
+        storeHttp.request("PUT", path`/store/auth-providers/${provider}`, loginSettingsSchema, {
+          body: saveLoginProviderRequestSchema.parse(body),
+        }),
+      setProviderEnabled: (provider: LoginProvider, enabled: boolean) =>
+        storeHttp.request("PATCH", path`/store/auth-providers/${provider}`, loginSettingsSchema, {
+          body: { enabled },
+        }),
+      testProvider: (provider: LoginProvider) =>
+        storeHttp.request(
+          "POST",
+          path`/store/auth-providers/${provider}/test`,
+          loginProviderTestSchema,
+        ),
+      /** 연결 해제 — 키를 지운다. 연결된 구매자 계정은 남는다 */
+      removeProvider: (provider: LoginProvider) =>
+        storeHttp.request("DELETE", path`/store/auth-providers/${provider}`, loginSettingsSchema),
+    },
+
+    /** 구매자 관리 — 조회 `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,8 @@ export * from "./schemas/auth";
 export * from "./schemas/category";
 export * from "./schemas/claim";
 export * from "./schemas/common";
+export * from "./schemas/customer";
+export * from "./schemas/login";
 export * from "./schemas/misc";
 export * from "./schemas/order";
 export * from "./schemas/payment";

package/src/schemas/customer.ts

@@ -0,0 +1,126 @@
+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(),
+    /** 소셜 가입에서 이메일을 받지 못했으면 null */
+    email: z.string().nullable(),
+    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().nullable(),
+  phone: z.string().nullable(),
+  joinedAt: z.string(),
+  point: z.number().int(),
+  marketingAgreed: z.boolean(),
+  loginMethods: z
+    .array(
+      z.object({
+        method: z.enum(["password", "kakao", "naver", "google"]),
+        /** 소셜 연결 시각. 비밀번호는 가입 시각 */
+        linkedAt: z.string(),
+      }),
+    )
+    .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/login.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+/** 소셜 로그인 공급자 */
+export const loginProviderSchema = z.enum(["kakao", "naver", "google"]);
+export type LoginProvider = z.infer<typeof loginProviderSchema>;
+
+/** 공급자 연결 상태 — 비밀 값은 앞 4자리만 */
+export const loginProviderStatusSchema = z.object({
+  provider: loginProviderSchema,
+  connected: z.boolean(),
+  /** 스토어프런트에서 사용 중인지. 연결 안 됐으면 false */
+  enabled: z.boolean(),
+  clientIdPrefix: z.string().nullable().describe("클라이언트 ID(카카오 REST API 키) 앞 4자리"),
+  secretPrefix: z.string().nullable(),
+  lastTestedAt: z.string().nullable(),
+  lastTestOk: z.boolean().nullable(),
+  linkedMemberCount: z.number().int().describe("이 공급자로 연결된 구매자 수"),
+  /** 이 공급자로만 로그인하는 구매자 수 — 연결을 해제하면 로그인할 방법이 없어진다 */
+  onlyMethodMemberCount: z.number().int(),
+  callbackUrl: z.url().describe("공급자 개발자 콘솔에 등록할 리디렉트 URI"),
+});
+export type LoginProviderStatus = z.infer<typeof loginProviderStatusSchema>;
+
+/** `GET /v1/store/login-settings` */
+export const loginSettingsSchema = z.object({
+  passwordLoginEnabled: z.boolean(),
+  /** 비밀번호로만 로그인하는 구매자 수 — 이메일·비밀번호를 끄면 이들은 로그인할 수 없다 */
+  passwordOnlyMemberCount: z.number().int(),
+  storefrontOrigins: z.array(z.string()),
+  providers: z.array(loginProviderStatusSchema),
+});
+export type LoginSettings = z.infer<typeof loginSettingsSchema>;
+
+/** `PATCH /v1/store/login-settings` */
+export const updateLoginSettingsRequestSchema = z.object({
+  passwordLoginEnabled: z.boolean(),
+});
+export type UpdateLoginSettingsRequest = z.infer<typeof updateLoginSettingsRequestSchema>;
+
+/** `PUT /v1/store/auth-providers/{provider}` — 저장 전에 연결 테스트를 한다 */
+export const saveLoginProviderRequestSchema = z.object({
+  clientId: z.string().trim().min(1).max(200),
+  clientSecret: z.string().trim().min(1).max(500),
+});
+export type SaveLoginProviderRequest = z.infer<typeof saveLoginProviderRequestSchema>;
+
+/** `PATCH /v1/store/auth-providers/{provider}` */
+export const updateLoginProviderRequestSchema = z.object({
+  enabled: z.boolean(),
+});
+
+/** 연결 테스트 결과 */
+export const loginProviderTestSchema = z.object({
+  ok: z.boolean(),
+  /** 실패 이유 — `INVALID_CLIENT`(키가 틀림)·`PROVIDER_UNAVAILABLE`(공급자 응답 없음) */
+  code: z.enum(["INVALID_CLIENT", "PROVIDER_UNAVAILABLE"]).nullable(),
+  testedAt: z.string(),
+});
+export type LoginProviderTest = z.infer<typeof loginProviderTestSchema>;

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

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