@sayren/store-sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,2300 @@
+import { a as WEBHOOK_HEADERS, i as WEBHOOK_EVENT_TYPE_HEADER, n as WEBHOOK_DELIVERY_ID_HEADER, o as WEBHOOK_SIGNATURE_HEADER, r as WEBHOOK_EVENT_ID_HEADER, s as WEBHOOK_USER_AGENT, t as WEBHOOK_DEFAULT_TOLERANCE_SEC } from "./webhook-headers-ap_exsb9.mjs";
+import { z } from "zod";
+//#region src/base64.ts
+/**
+* base64 인코딩 헬퍼 — 웹 표준(`btoa` + `TextEncoder`)만 사용한다.
+*
+* 이 패키지는 브라우저/서버 공용 entrypoint 하나로 배포되므로 Node 전용 `Buffer`에
+* 의존하지 않는다. `btoa`는 Latin-1 코드유닛만 받기 때문에 문자열은 반드시
+* UTF-8 바이트로 먼저 인코딩한 뒤 넘긴다 — 그래야 non-ASCII 입력에서도
+* `Buffer.from(text, "utf8").toString("base64")`와 동일한 결과가 나온다.
+*/
+/** 바이트 배열 → 표준 base64 (패딩 포함) */
+function base64FromBytes(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+/** 바이트 배열 → base64url (RFC 4648 §5, 패딩 없음) */
+function base64UrlFromBytes(bytes) {
+	return base64FromBytes(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+* 문자열 → UTF-8 base64. `btoa(text)`를 직접 쓰면 Latin-1로 해석돼
+* non-ASCII에서 잘못된 바이트가 나오거나(예: "café") 예외가 난다(예: "🔑").
+*/
+function base64Utf8(text) {
+	return base64FromBytes(new TextEncoder().encode(text));
+}
+//#endregion
+//#region src/http.ts
+/** 표준 엔벨로프의 $.error 상세 */
+const errorDetailSchema = z.object({
+	code: z.string(),
+	message: z.string(),
+	traceId: z.string().optional(),
+	/**
+	* 에러 코드별 보조 데이터(선택). 예: 관리 API `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의
+	* `{ conditions: LiveGateCondition[] }`. 형태는 에러 코드마다 다르므로 소비측이 코드별 스키마로 다시 파싱한다
+	*/
+	details: z.record(z.string(), z.unknown()).optional().catch(void 0)
+});
+/** 표준 응답 엔벨로프 — $.meta / $.data / $.error */
+const envelopeSchema = z.object({
+	meta: z.object({
+		status: z.number(),
+		code: z.string(),
+		message: z.string(),
+		isSuccess: z.boolean()
+	}),
+	data: z.unknown().optional(),
+	/** 구형 필드 — data로 개명되기 전 응답과의 전환기 호환 */
+	content: z.unknown().optional(),
+	error: errorDetailSchema.nullable()
+});
+/** OAuth 프로토콜 표면의 평면 에러 (RFC 6749 §5.2, RFC 7591 §3.2.2) */
+const oauthErrorSchema = z.object({
+	error: z.string(),
+	error_description: z.string().optional()
+});
+/** 표준 엔벨로프면 $.data(구형 $.content)를, 아니면(평면 응답) 본문 전체를 반환 */
+function unwrapData(json) {
+	const envelope = envelopeSchema.safeParse(json);
+	if (!envelope.success) return json;
+	return envelope.data.data ?? envelope.data.content ?? null;
+}
+var ApiError = class extends Error {
+	status;
+	code;
+	traceId;
+	body;
+	details;
+	constructor(status, code, message, traceId, body, details) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.traceId = traceId;
+		this.body = body;
+		this.details = details;
+		this.name = "ApiError";
+	}
+};
+/**
+* 에러 응답 본문 → ApiError 구성 (에러 형태의 단일 원천).
+* 표준 엔벨로프($.error) 우선, 구형 평면 에러({ code, message }), OAuth 평면 에러
+* ({ error, error_description } → code=error, message=error_description) 순으로 폴백하고,
+* 모두 아니면 UNKNOWN. createHttp의 send와 세션(userinfo 등 raw fetch 경로)이 동일한 에러 모양을 내도록 공유한다.
+*/
+function toApiError(status, raw) {
+	const envelope = envelopeSchema.safeParse(raw);
+	const detail = envelope.success ? envelope.data.error : errorDetailSchema.safeParse(raw).data ?? null;
+	if (detail) return new ApiError(status, detail.code, detail.message, detail.traceId, raw, detail.details);
+	const oauth = envelope.success ? null : oauthErrorSchema.safeParse(raw).data;
+	if (oauth) return new ApiError(status, oauth.error, oauth.error_description ?? oauth.error, void 0, raw);
+	return new ApiError(status, "UNKNOWN", `HTTP ${status}`, void 0, raw);
+}
+/**
+* 경로 템플릿 태그 — 보간 값(경로 파라미터)마다 encodeURIComponent를 적용한다.
+* `/`·`?`·`#` 등이 섞인 id가 다른 경로·쿼리로 해석되지 않게 한다. 예: path`/products/${id}`
+*/
+function path(strings, ...params) {
+	return strings.reduce((acc, part, i) => acc + part + (i < params.length ? encodeURIComponent(String(params[i])) : ""), "");
+}
+function resolveToken(source) {
+	return (typeof source === "function" ? source() : source) ?? null;
+}
+function buildQuery(query) {
+	if (!query) return "";
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) if (value !== void 0) params.set(key, String(value));
+	const qs = params.toString();
+	return qs ? `?${qs}` : "";
+}
+function createHttp(options) {
+	const fetchFn = options.fetch ?? globalThis.fetch;
+	async function send(method, path, request, retried = false) {
+		const url = `${options.baseUrl}${path}${buildQuery(request?.query)}`;
+		const headers = {
+			...request?.body !== void 0 ? { "content-type": "application/json" } : {},
+			...options.headers?.(),
+			...request?.headers
+		};
+		const response = await fetchFn(url, {
+			method,
+			headers,
+			body: request?.body !== void 0 ? JSON.stringify(request.body) : void 0
+		});
+		options.onResponse?.(response);
+		if (response.status === 401 && !retried && options.refresh) {
+			if (await options.refresh()) return send(method, path, request, true);
+		}
+		if (!response.ok) {
+			if (response.status === 401) options.onUnauthorized?.();
+			const raw = await response.json().catch(() => null);
+			throw toApiError(response.status, raw);
+		}
+		return response;
+	}
+	return {
+		async request(method, path, schema, request) {
+			const json = await (await send(method, path, request)).json();
+			return schema.parse(unwrapData(json));
+		},
+		async requestVoid(method, path, request) {
+			await send(method, path, request);
+		}
+	};
+}
+//#endregion
+//#region src/schemas/api-client.ts
+/**
+* 앱(OAuth 클라이언트) 관리 — `/v1/store/api-clients` (auth-spec 부록 B-13).
+* 등록은 DCR(`POST /v1/oauth2/register`, RFC 7591)이 담당하고, 이 스키마는 등록 이후의
+* 목록·상세·시크릿 재발급·비활성화 응답 계약이다. 시크릿 해시는 어떤 응답에도 포함되지 않는다.
+*/
+const apiClientTypeSchema = z.enum(["public", "confidential"]).describe("클라이언트 유형. `public`=시크릿 없음(PKCE 로그인용), `confidential`=시크릿 보유(서버 간 연동용)");
+const apiClientStatusSchema = z.enum(["ACTIVE", "REVOKED"]).describe("상태. `REVOKED`는 비활성화된 클라이언트이며 다시 활성화할 수 없다");
+const apiClientSchema = z.object({
+	clientId: z.string().describe("클라이언트 ID (`client_id`)"),
+	name: z.string().describe("클라이언트 이름 (`client_name`)"),
+	type: apiClientTypeSchema,
+	status: apiClientStatusSchema,
+	redirectUris: z.array(z.string()).describe("authorization_code 리다이렉트 URI 허용 목록 (정확 일치)"),
+	scopes: z.array(z.string()).describe("클라이언트가 요청할 수 있는 최대 스코프"),
+	grantTypes: z.array(z.string()).describe("허용된 grant_type 목록"),
+	secretPrefix: z.string().nullable().describe("시크릿 앞부분(식별용, 인증에 사용할 수 없음). public 클라이언트와 시크릿 앞부분이 기록되기 전에 등록된 클라이언트는 null"),
+	createdBy: z.string().nullable().describe("등록자 userId. 등록자 기록이 도입되기 전에 등록된 클라이언트는 null"),
+	createdByName: z.string().nullable().describe("등록자 이름 (표시용). 계정이 없으면 null"),
+	createdByEmail: z.string().nullable().describe("등록자 이메일 (표시용). 계정이 없으면 null"),
+	createdAt: z.string().describe("등록 일시 (ISO 8601)"),
+	revokedAt: z.string().nullable().describe("비활성화 일시 (ISO 8601). 활성 상태면 null")
+});
+/** 시크릿 재발급 응답 — 평문 시크릿은 이 응답에서 단 한 번만 노출된다 */
+const apiClientSecretRotatedSchema = apiClientSchema.extend({ clientSecret: z.string().describe("새 클라이언트 시크릿 평문. 이 응답에서만 노출되며 다시 조회할 수 없다") });
+const apiClientListQuerySchema = z.object({ status: apiClientStatusSchema.optional().describe("상태 필터. 생략하면 전체") });
+/**
+* Dynamic Client Registration 요청 (RFC 7591 §2, auth-spec §12) — `POST /v1/oauth2/register`.
+* OAuth 프로토콜 표면이라 필드명이 snake_case이고 응답·등록 오류는 평면 JSON이다.
+* 생략한 필드는 서버 기본값을 따른다(SDK가 기본값을 채워 보내지 않는다).
+*/
+const oauthClientRegistrationRequestSchema = z.object({
+	client_name: z.string().min(1).max(80).describe("클라이언트 이름 (1~80자)"),
+	token_endpoint_auth_method: z.enum(["none", "client_secret_basic"]).optional().describe("토큰 엔드포인트 인증 방식. `none`=public(시크릿 없음), `client_secret_basic`=confidential. 생략하면 `client_secret_basic`"),
+	redirect_uris: z.array(z.string()).max(10).optional().describe("리다이렉트 URI 목록(최대 10개). authorization_code에는 필수이며 https(개발용 루프백 http 제외)만 허용"),
+	grant_types: z.array(z.enum([
+		"authorization_code",
+		"refresh_token",
+		"client_credentials",
+		"urn:ietf:params:oauth:grant-type:token-exchange"
+	])).min(1).optional().describe("허용할 grant_type 목록. 생략하면 `client_credentials`"),
+	scope: z.string().optional().describe("공백 구분 스코프. 등록자 보유 스코프 이내여야 한다. 생략하면 confidential은 등록자 스코프, public은 `stores:read`")
+});
+/** Dynamic Client Registration 응답 (RFC 7591 §3.2.1) — client_secret은 이 응답에서만 노출된다 */
+const oauthClientRegistrationResponseSchema = z.object({
+	client_id: z.string().describe("발급된 클라이언트 ID"),
+	client_secret: z.string().optional().describe("클라이언트 시크릿 평문. confidential만 있으며 이 응답에서만 노출된다"),
+	client_secret_expires_at: z.number().int().optional().describe("시크릿 만료 시각(epoch 초). 0은 만료 없음. confidential만 있다"),
+	client_id_issued_at: z.number().int().describe("발급 시각 (epoch 초)"),
+	client_name: z.string(),
+	token_endpoint_auth_method: z.enum(["none", "client_secret_basic"]),
+	redirect_uris: z.array(z.string()),
+	grant_types: z.array(z.string()),
+	scope: z.string().describe("부여된 스코프 (공백 구분)")
+});
+//#endregion
+//#region src/schemas/api-log.ts
+/**
+* API 로그 — `/v1/api-logs`. 스토어가 해석된 관리 API(`/v1/**`) 요청을 7일간 보관한다.
+* 인증에 실패해 스토어를 알 수 없는 요청(401 등)은 기록되지 않는다.
+* Authorization·쿠키 헤더, 요청 본문, 개인정보는 저장하지 않는다.
+*/
+const apiLogPrincipalTypeSchema = z.enum([
+	"USER",
+	"PAT",
+	"CLIENT"
+]).describe("호출 주체 유형. `USER`=콘솔 사용자, `PAT`=API 토큰, `CLIENT`=앱(OAuth 클라이언트)");
+const apiLogPrincipalSchema = z.object({
+	type: apiLogPrincipalTypeSchema,
+	id: z.string().describe("호출 주체 ID. `USER`=userId, `PAT`=API 토큰 ID, `CLIENT`=clientId"),
+	name: z.string().nullable().describe("기록 시점의 표시 이름 (사용자 이름·API 토큰 이름·앱 이름). 알 수 없으면 null")
+});
+const apiLogErrorSchema = z.object({
+	code: z.string().describe("에러 코드. 에러 응답 `error.code`와 같다"),
+	message: z.string().describe("에러 메시지. 에러 응답 `error.message`와 같다")
+});
+const apiLogSchema = z.object({
+	logId: z.string().describe("로그 ID"),
+	occurredAt: z.string().describe("요청 일시 (ISO 8601)"),
+	method: z.string().describe("HTTP 메서드"),
+	path: z.string().describe("요청 경로와 쿼리. token·secret·code·password·email·phone 등 민감한 쿼리 값은 `***`로 가린다"),
+	statusCode: z.number().int().describe("응답 HTTP 상태 코드"),
+	latencyMs: z.number().int().min(0).describe("처리 시간(ms)"),
+	principal: apiLogPrincipalSchema,
+	traceId: z.string().nullable().describe("추적 ID. 에러 응답의 `error.traceId`와 같다"),
+	error: apiLogErrorSchema.nullable().describe("에러 응답 요약. 4xx·5xx일 때만 값이 있다")
+});
+const apiLogStatusFilterSchema = z.enum([
+	"2xx",
+	"3xx",
+	"4xx",
+	"5xx",
+	"error"
+]).describe("응답 상태 필터. `error`는 4xx·5xx 전체");
+/** API 로그 조회 쿼리 — `GET /api-logs` */
+const apiLogListQuerySchema = z.object({
+	from: z.string().optional().describe("조회 시작 일시 (ISO 8601, 포함). 보관 기간은 7일이다"),
+	to: z.string().optional().describe("조회 종료 일시 (ISO 8601, 미포함)"),
+	principalType: z.union([z.string(), z.array(z.string())]).transform((value) => (Array.isArray(value) ? value : [value]).flatMap((part) => part.split(",")).map((part) => part.trim()).filter((part) => part.length > 0)).pipe(z.array(apiLogPrincipalTypeSchema).min(1)).optional().describe("호출 주체 유형 필터. 여러 개는 쉼표로 구분한다 (예: `PAT,CLIENT`). 파싱 결과는 배열로 정규화된다"),
+	principalId: z.string().optional().describe("호출 주체 ID 필터"),
+	status: apiLogStatusFilterSchema.optional(),
+	q: z.string().optional().describe("경로 부분 일치 검색어"),
+	cursor: z.string().optional().describe("이전 응답의 `nextCursor`. 생략하면 가장 최신부터"),
+	limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50)")
+});
+/** API 로그 목록 응답 (최신순, 커서 페이지네이션) */
+const apiLogPageSchema = z.object({
+	items: z.array(apiLogSchema),
+	nextCursor: z.string().nullable().describe("다음 페이지 커서. 마지막 페이지면 null")
+});
+/**
+* API 로그 요약 — `GET /api-logs/summary`. 연동 트래픽(호출 주체 `PAT`·`CLIENT`)만 집계하며
+* 콘솔 사용자(`USER`) 요청은 제외한다
+*/
+const apiLogSummarySchema = z.object({
+	windowHours: z.number().int().describe("집계 구간(시간). 최근 24시간"),
+	total: z.number().int().min(0).describe("구간 내 연동 요청 수 (호출 주체 `PAT`·`CLIENT`, 콘솔 사용자 제외)"),
+	errors: z.number().int().min(0).describe("구간 내 연동 요청 중 4xx·5xx 응답 수"),
+	serverErrors: z.number().int().min(0).describe("구간 내 연동 요청 중 5xx 응답 수")
+});
+//#endregion
+//#region src/schemas/auth.ts
+const storeRoleSchema = z.enum([
+	"OWNER",
+	"ADMIN",
+	"STAFF"
+]);
+const userTokenResponseSchema = z.object({
+	access_token: z.string(),
+	token_type: z.literal("Bearer"),
+	expires_in: z.number().int(),
+	refresh_token: z.string().optional()
+});
+/** client_credentials 응답 (RFC 6749 §4.4.3) — storeToken 직발급, refresh 없음 */
+const clientCredentialsTokenResponseSchema = z.object({
+	access_token: z.string(),
+	token_type: z.literal("Bearer"),
+	expires_in: z.number().int(),
+	scope: z.string()
+});
+const storeTokenResponseSchema = z.object({
+	access_token: z.string(),
+	token_type: z.literal("Bearer"),
+	expires_in: z.number().int(),
+	storeId: z.string(),
+	role: storeRoleSchema,
+	scopes: z.array(z.string())
+});
+const myStoreSchema = z.object({
+	storeId: z.string(),
+	storeName: z.string(),
+	storeCode: z.string(),
+	role: storeRoleSchema,
+	status: z.enum([
+		"ACTIVE",
+		"SUSPENDED",
+		"CLOSED"
+	])
+});
+const myAccountSchema = z.object({
+	userId: z.string(),
+	email: z.email(),
+	name: z.string(),
+	storeCount: z.number().int(),
+	createdAt: z.string()
+});
+/** API 토큰(PAT) — 목록/조회 뷰 (평문·해시 미포함) */
+const apiTokenSchema = z.object({
+	tokenId: z.string(),
+	name: z.string(),
+	prefix: z.string(),
+	scopes: z.array(z.string()),
+	createdBy: z.string().describe("발급자 userId"),
+	createdByName: z.string().nullable().describe("발급자 이름 (표시용). 계정이 없으면 null"),
+	createdByEmail: z.string().nullable().describe("발급자 이메일 (표시용). 계정이 없으면 null"),
+	createdAt: z.string(),
+	expiresAt: z.string().nullable(),
+	lastUsedAt: z.string().nullable()
+});
+/** 생성 응답 — 평문 토큰은 이 응답에서 단 한 번만 노출된다 */
+const apiTokenCreatedSchema = apiTokenSchema.extend({ token: z.string() });
+const apiTokenCreateRequestSchema = z.object({
+	name: z.string().min(1).max(50),
+	scopes: z.array(z.string()).min(1),
+	/** 일 단위 만료. null = 무기한, 생략 = 90일 */
+	expiresInDays: z.number().int().nullable().optional()
+});
+//#endregion
+//#region src/schemas/category.ts
+const categoryProductSortSchema = z.enum([
+	"RECENT",
+	"POPULAR",
+	"PRICE_LOW",
+	"PRICE_HIGH",
+	"NAME"
+]);
+const categorySchema = z.object({
+	categoryId: z.string(),
+	storeId: z.string(),
+	name: z.string(),
+	parentId: z.string().nullable(),
+	path: z.string(),
+	depth: z.number().int().min(1).max(4),
+	leaf: z.boolean(),
+	sortOrder: z.number().int(),
+	visible: z.boolean(),
+	showPc: z.boolean(),
+	showMobile: z.boolean(),
+	productSort: categoryProductSortSchema,
+	metaTitle: z.string().nullable(),
+	metaDescription: z.string().nullable(),
+	metaKeywords: z.string().nullable(),
+	createdAt: z.string(),
+	updatedAt: z.string()
+});
+const categoryTreeNodeSchema = categorySchema.extend({ children: z.lazy(() => z.array(categoryTreeNodeSchema)) });
+const categoryWithPathSchema = categorySchema.extend({
+	fullPath: z.string(),
+	ancestors: z.array(categorySchema),
+	childCount: z.number().int()
+});
+const categorySearchResultSchema = categorySchema.extend({
+	fullPath: z.string(),
+	ancestors: z.array(categorySchema)
+});
+const categoryAttributeSchema = z.object({
+	attributeId: z.string(),
+	name: z.string(),
+	required: z.boolean(),
+	inputType: z.enum([
+		"SELECT",
+		"MULTI_SELECT",
+		"TEXT",
+		"NUMBER"
+	]),
+	unit: z.string().nullable(),
+	allowedValues: z.array(z.string()).optional()
+});
+const categoryCreateRequestSchema = z.object({
+	name: z.string().min(1).max(100),
+	parentId: z.string().nullable().optional(),
+	sortOrder: z.number().int().optional(),
+	visible: z.boolean().optional(),
+	showPc: z.boolean().optional(),
+	showMobile: z.boolean().optional(),
+	productSort: categoryProductSortSchema.optional(),
+	metaTitle: z.string().max(100).nullable().optional(),
+	metaDescription: z.string().max(300).nullable().optional(),
+	metaKeywords: z.string().max(200).nullable().optional()
+});
+const categoryPatchRequestSchema = z.object({
+	name: z.string().min(1).max(100).optional(),
+	parentId: z.string().nullable().optional(),
+	sortOrder: z.number().int().optional(),
+	visible: z.boolean().optional(),
+	showPc: z.boolean().optional(),
+	showMobile: z.boolean().optional(),
+	productSort: categoryProductSortSchema.optional(),
+	metaTitle: z.string().max(100).nullable().optional(),
+	metaDescription: z.string().max(300).nullable().optional(),
+	metaKeywords: z.string().max(200).nullable().optional()
+});
+const categoryDeleteStrategySchema = z.enum(["reparent", "cascade"]);
+//#endregion
+//#region src/schemas/claim.ts
+const claimTypeSchema = z.enum([
+	"CANCEL",
+	"RETURN",
+	"EXCHANGE"
+]);
+const claimStatusSchema = z.enum([
+	"REQUESTED",
+	"HELD",
+	"COLLECTING",
+	"COLLECTED",
+	"REDELIVERING",
+	"APPROVED",
+	"REJECTED",
+	"COMPLETED",
+	"WITHDRAWN"
+]);
+const claimReasonSchema = z.enum([
+	"CHANGE_OF_MIND",
+	"WRONG_ORDER",
+	"DEFECTIVE",
+	"WRONG_DELIVERY",
+	"DIFFERENT_FROM_PAGE",
+	"DELAY"
+]);
+const claimSchema = z.object({
+	claimId: z.string(),
+	type: claimTypeSchema,
+	status: claimStatusSchema,
+	orderId: z.string(),
+	orderItemId: z.string(),
+	productName: z.string(),
+	quantity: z.number().int(),
+	reason: claimReasonSchema,
+	reasonDetail: z.string().nullable(),
+	responsibility: z.enum(["BUYER", "SELLER"]),
+	claimDeliveryFee: z.number().int(),
+	expectedRefundAmount: z.number().int().nullable(),
+	exchangeOption: z.object({
+		optionId: z.string(),
+		optionName: z.string()
+	}).nullable(),
+	collect: z.object({
+		method: z.enum(["SELLER_PICKUP", "BUYER_SEND"]),
+		carrierCode: z.string().nullable(),
+		trackingNumber: z.string().nullable()
+	}).nullable(),
+	requestedAt: z.string(),
+	completedAt: z.string().nullable()
+});
+const rejectClaimRequestSchema = z.object({
+	reason: z.enum([
+		"USED_PRODUCT",
+		"MISSING_COMPONENT",
+		"PERIOD_EXPIRED",
+		"BUYER_FAULT_DAMAGE",
+		"ETC"
+	]),
+	detail: z.string().min(10).max(1e3),
+	evidenceImages: z.array(z.url()).max(5).optional()
+});
+const approveClaimResultSchema = z.object({
+	claimId: z.string(),
+	refundAmount: z.number().int(),
+	deductAmount: z.number().int(),
+	refundedAt: z.string()
+});
+//#endregion
+//#region src/schemas/common.ts
+const pageInfoSchema = z.object({
+	page: z.number().int(),
+	size: z.number().int(),
+	totalElements: z.number().int(),
+	totalPages: z.number().int()
+});
+function pageSchema(item) {
+	return pageInfoSchema.extend({ contents: z.array(item) });
+}
+const bulkResultSchema = z.object({
+	succeeded: z.array(z.string()),
+	failed: z.array(z.object({
+		id: z.string().optional(),
+		productId: z.string().optional(),
+		orderItemId: z.string().optional(),
+		code: z.string(),
+		message: z.string()
+	}))
+});
+const orderItemStatusSchema = z.enum([
+	"PAYMENT_WAITING",
+	"PAID",
+	"CONFIRMED",
+	"DISPATCHED",
+	"DELIVERING",
+	"DELIVERED",
+	"PURCHASE_DECIDED",
+	"CANCELED"
+]);
+const changeTypeSchema = z.enum([
+	"ORDER.PAID",
+	"ORDER.CONFIRMED",
+	"ORDER.DISPATCHED",
+	"ORDER.DELIVERED",
+	"ORDER.PURCHASE_DECIDED",
+	"CLAIM.CANCEL_REQUESTED",
+	"CLAIM.RETURN_REQUESTED",
+	"CLAIM.EXCHANGE_REQUESTED",
+	"ORDER.ADDRESS_CHANGE_REQUESTED"
+]);
+//#endregion
+//#region src/schemas/misc.ts
+const inquirySchema = z.object({
+	inquiryId: z.string(),
+	productId: z.string(),
+	productName: z.string(),
+	orderItemId: z.string().nullable(),
+	category: z.enum([
+		"PRODUCT",
+		"DELIVERY",
+		"RETURN",
+		"EXCHANGE",
+		"ETC"
+	]),
+	content: z.string(),
+	secret: z.boolean(),
+	writerMaskedName: z.string(),
+	answered: z.boolean(),
+	answer: z.object({
+		content: z.string(),
+		answeredAt: z.string(),
+		modifiedCount: z.number().int().max(1)
+	}).nullable(),
+	createdAt: z.string()
+});
+const customerInquiryCategorySchema = z.enum([
+	"DELIVERY",
+	"RETURN",
+	"EXCHANGE",
+	"PAYMENT",
+	"ETC"
+]);
+/** 셀러 뷰 1:1 문의 — 작성자 마스킹명 + 답변 수정횟수 포함 */
+const sellerCustomerInquirySchema = z.object({
+	inquiryId: z.string(),
+	memberMaskedName: z.string(),
+	category: customerInquiryCategorySchema,
+	title: z.string(),
+	content: z.string(),
+	orderItemId: z.string().nullable(),
+	answered: z.boolean(),
+	answer: z.object({
+		content: z.string(),
+		answeredAt: z.string(),
+		modifiedCount: z.number().int().max(1)
+	}).nullable(),
+	createdAt: z.string()
+});
+const settlementStatusSchema = z.enum([
+	"SCHEDULED",
+	"PAID",
+	"HELD"
+]);
+const settlementSummarySchema = z.object({
+	settlementId: z.string(),
+	settlementDate: z.string(),
+	payoutDate: z.string().nullable(),
+	status: settlementStatusSchema,
+	totalPaymentAmount: z.number().int(),
+	totalCommission: z.number().int(),
+	totalDeliveryFee: z.number().int(),
+	adjustmentAmount: z.number().int(),
+	settlementAmount: z.number().int(),
+	itemCount: z.number().int()
+});
+const settlementDetailSchema = z.object({
+	orderItemId: z.string(),
+	productName: z.string(),
+	settlementType: z.enum([
+		"SALE",
+		"REFUND_DEDUCTION",
+		"ADJUSTMENT"
+	]),
+	paymentAmount: z.number().int(),
+	salesCommission: z.number().int(),
+	paymentCommission: z.number().int(),
+	commissionRate: z.number(),
+	deliveryFee: z.number().int(),
+	settlementAmount: z.number().int(),
+	purchaseDecidedAt: z.string().nullable()
+});
+const eventTypeSchema = z.enum([
+	"ORDER.PAID",
+	"ORDER.CONFIRMED",
+	"ORDER.DISPATCHED",
+	"ORDER.DELIVERED",
+	"ORDER.PURCHASE_DECIDED",
+	"ORDER.ADDRESS_CHANGE_REQUESTED",
+	"CLAIM.CANCEL_REQUESTED",
+	"CLAIM.RETURN_REQUESTED",
+	"CLAIM.EXCHANGE_REQUESTED",
+	"CLAIM.COMPLETED",
+	"INQUIRY.CREATED",
+	"REVIEW.CREATED",
+	"PRODUCT.OUT_OF_STOCK"
+]);
+const webhookStatusSchema = z.enum(["ACTIVE", "SUSPENDED"]).describe("구독 상태. `ACTIVE`=발송 대상, `SUSPENDED`=24시간 이상 연속 전송 실패로 발송이 정지된 상태. 정지 중 발생한 이벤트는 적재하지 않는다. 재개(`POST /webhooks/{id}/resume`)하거나 구독을 수정하면 ACTIVE로 돌아간다");
+const webhookSchema = z.object({
+	webhookId: z.string(),
+	url: z.url(),
+	eventTypes: z.array(eventTypeSchema),
+	status: webhookStatusSchema,
+	secretPrefix: z.string().describe("서명 시크릿 앞부분(식별용, 서명 검증에 사용할 수 없음). 예: `whsec_1a2b`"),
+	suspendedAt: z.string().nullable().describe("발송이 정지된 일시 (ISO 8601). `ACTIVE`면 null"),
+	createdAt: z.string()
+});
+/** 등록 응답 — 서명 시크릿 평문은 이 응답에서만 노출된다 */
+const webhookCreatedSchema = webhookSchema.extend({ secret: z.string().describe("서명 시크릿 평문. 등록 응답에서만 노출되며 다시 조회할 수 없다") });
+/** 시크릿 교체 응답 */
+const webhookSecretRotatedSchema = z.object({
+	secret: z.string().describe("새 서명 시크릿 평문. 이 응답에서만 노출된다"),
+	oldSecretExpiresAt: z.string().describe("기존 시크릿의 병행 유효 종료 일시 (ISO 8601). 이때까지는 기존 시크릿 서명도 함께 붙는다")
+});
+const webhookDeliveryStatusSchema = z.enum([
+	"PENDING",
+	"PENDING_RETRY",
+	"SUCCESS",
+	"FAILED"
+]).describe("전송 상태. `PENDING`=첫 시도 전, `PENDING_RETRY`=실패 후 재시도 대기, `SUCCESS`=2xx 응답 수신, `FAILED`=재시도를 모두 소진했거나 구독 정지로 종료");
+const webhookDeliveryErrorCodeSchema = z.enum([
+	"TIMEOUT",
+	"CONNECTION_FAILED",
+	"BLOCKED_ADDRESS",
+	"NON_2XX",
+	"WEBHOOK_SUSPENDED"
+]).describe("전송 실패 사유. `TIMEOUT`=10초 안에 응답 없음, `CONNECTION_FAILED`=연결 실패(DNS·TLS 포함), `BLOCKED_ADDRESS`=사설·루프백 등 전송이 허용되지 않는 주소, `NON_2XX`=2xx가 아닌 응답(리다이렉트 포함), `WEBHOOK_SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨");
+/** 웹훅 전송 기록 한 건 (전송 기록 조회 항목) */
+const webhookDeliverySchema = z.object({
+	deliveryId: z.string().describe("전송 기록 ID. 수신 요청의 `Sayren-Delivery-Id` 헤더 값"),
+	eventId: z.string().describe("이벤트 ID. 재시도·재전송해도 같은 이벤트면 같은 값이다. 수신 측 중복 제거 키로 쓴다"),
+	eventType: eventTypeSchema,
+	url: z.string().describe("전송 시점의 대상 URL"),
+	status: webhookDeliveryStatusSchema,
+	responseStatusCode: z.number().int().nullable().describe("마지막 시도의 HTTP 응답 코드. 미시도·연결 실패·타임아웃·차단이면 null"),
+	responseTimeMs: z.number().int().nullable().describe("마지막 시도의 응답 시간(ms). 미시도·연결 실패면 null"),
+	responseBodyExcerpt: z.string().nullable().describe("마지막 시도의 응답 본문 앞부분(최대 1,024자). 응답이 없으면 null"),
+	errorCode: webhookDeliveryErrorCodeSchema.nullable().describe("마지막 시도의 실패 사유. 성공했거나 미시도면 null"),
+	attemptCount: z.number().int().min(0).describe("지금까지의 시도 횟수. 최초 시도 1회 + 재시도 최대 4회"),
+	createdAt: z.string().describe("전송 기록이 적재된 일시 (ISO 8601)"),
+	attemptedAt: z.string().nullable().describe("마지막 시도 일시 (ISO 8601). 미시도면 null"),
+	nextAttemptAt: z.string().nullable().describe("다음 시도 예정 일시 (ISO 8601). `PENDING`·`PENDING_RETRY`일 때만 값이 있다"),
+	redeliveryOf: z.string().nullable().describe("수동 재전송으로 생긴 기록이면 원본 전송 기록 ID. 아니면 null"),
+	redeliveredAs: z.string().nullable().describe("이 기록을 원본으로 수동 재전송해 생긴 기록의 전송 기록 ID. 아직 재전송하지 않았으면 null. 재전송은 원본당 1회다")
+});
+/** 전송 기록 조회 쿼리 — `GET /webhooks/{id}/deliveries` */
+const webhookDeliveryListQuerySchema = z.object({
+	status: webhookDeliveryStatusSchema.optional().describe("전송 상태 필터. 생략하면 전체"),
+	limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50). 최신 적재순으로 반환하며 보관 기간은 30일이다")
+});
+/** 실패 건 일괄 재전송 응답 — `POST /webhooks/{id}/deliveries/redeliver-failed` */
+const webhookRedeliverFailedResultSchema = z.object({ queued: z.number().int().min(0).describe("재전송 대기열에 올린 건수. 최근 72시간의 `FAILED` 중 아직 재전송되지 않은 건이 대상이며 최대 500건이다") });
+const webhookTestRequestSchema = z.object({ eventType: eventTypeSchema.describe("샘플 페이로드로 보낼 이벤트 타입") });
+/** 테스트 이벤트 발송 결과 (동기 반환). 재시도·정지 판정·전송 기록이 없다 */
+const webhookTestResultSchema = z.object({
+	responseStatusCode: z.number().int().nullable().describe("수신 서버의 HTTP 응답 코드. 연결 실패·타임아웃·차단이면 null"),
+	responseTimeMs: z.number().int().nullable().describe("응답 시간(ms). 연결 실패면 null"),
+	errorCode: webhookDeliveryErrorCodeSchema.nullable().describe("실패 사유. 2xx 응답이면 null")
+});
+const webhookRequestSchema = z.object({
+	url: z.url().startsWith("https://", "웹훅 URL은 HTTPS만 허용됩니다"),
+	eventTypes: z.array(eventTypeSchema).min(1)
+});
+const reviewSchema = z.object({
+	reviewId: z.string(),
+	productId: z.string(),
+	productName: z.string(),
+	orderItemId: z.string(),
+	optionName: z.string().nullable(),
+	rating: z.number().int().min(1).max(5),
+	content: z.string(),
+	images: z.array(z.url()),
+	writerMaskedName: z.string(),
+	blinded: z.boolean(),
+	reply: z.object({
+		content: z.string(),
+		repliedAt: z.string(),
+		updatedAt: z.string().nullable()
+	}).nullable(),
+	createdAt: z.string()
+});
+//#endregion
+//#region src/schemas/order.ts
+const orderSummarySchema = z.object({
+	orderId: z.string(),
+	ordererName: z.string(),
+	itemCount: z.number().int(),
+	totalAmount: z.number().int(),
+	representativeStatus: orderItemStatusSchema,
+	orderedAt: z.string(),
+	testPayment: z.boolean().describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았어요. 상품을 발송하지 않도록 주의하세요")
+});
+const shippingAddressSchema = z.object({
+	receiverName: z.string(),
+	phone: z.string(),
+	zipCode: z.string(),
+	address1: z.string(),
+	address2: z.string().nullish(),
+	deliveryMemo: z.string().nullish(),
+	entranceCode: z.string().nullish()
+});
+const orderItemSchema = z.object({
+	orderItemId: z.string(),
+	orderId: z.string(),
+	status: orderItemStatusSchema,
+	claimStatus: z.enum([
+		"CANCEL_REQUESTED",
+		"RETURN_REQUESTED",
+		"EXCHANGE_REQUESTED"
+	]).nullable(),
+	productId: z.string(),
+	productName: z.string(),
+	optionId: z.string().nullable(),
+	optionName: z.string().nullable(),
+	sellerCode: z.string().nullable(),
+	quantity: z.number().int(),
+	unitPrice: z.number().int(),
+	discountAmount: z.number().int(),
+	totalPrice: z.number().int(),
+	hold: z.object({
+		reason: z.string(),
+		expectedDispatchDate: z.string()
+	}).nullable(),
+	autoDecisionDate: z.string().nullable(),
+	sellerMemo: z.string().nullable(),
+	orderedAt: z.string(),
+	lastChangedAt: z.string(),
+	lastChangedType: changeTypeSchema,
+	testPayment: z.boolean().describe("소속 주문이 테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았어요")
+});
+const orderSchema = z.object({
+	orderId: z.string(),
+	orderedAt: z.string(),
+	orderer: z.object({
+		name: z.string(),
+		phone: z.string(),
+		email: z.email().optional()
+	}),
+	shippingAddress: shippingAddressSchema,
+	payment: z.object({
+		method: z.enum([
+			"CARD",
+			"BANK_TRANSFER",
+			"VIRTUAL_ACCOUNT",
+			"MOBILE",
+			"POINT",
+			"MIXED"
+		]).describe("method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다"),
+		approvedMethod: z.string().nullable().optional().default(null).describe("실제 결제수단. method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다. 현재 값은 `pgPaymentMethodSchema`(`PgPaymentMethod`: CARD·BANK_TRANSFER·VIRTUAL_ACCOUNT·MOBILE·EASY_PAY)이고 매출 리포트·스토어프론트·환불 원장과 같은 값이다. 값이 추가될 수 있어 문자열로 받는다. PG가 알려 주지 않았으면 요청 수단, 시도 기록이 없는 오래된 주문은 null. 서버는 항상 싣는다"),
+		productAmount: z.number().int(),
+		deliveryFee: z.number().int(),
+		discountAmount: z.number().int(),
+		totalAmount: z.number().int(),
+		paidAt: z.string().nullable()
+	}),
+	testPayment: z.boolean().describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았어요. 상품을 발송하지 않도록 주의하세요"),
+	items: z.array(orderItemSchema)
+});
+/** 주문 목록 응답 — `GET /v1/orders` */
+const orderSummaryPageSchema = pageSchema(orderSummarySchema);
+/** 주문상품 변경 목록 응답 — `GET /v1/order-items` */
+const orderItemPageSchema = pageSchema(orderItemSchema);
+const testPaymentQuery = z.enum(["true", "false"]).optional().describe("테스트 결제(샌드박스 결제) 필터. `true`면 테스트 결제만, `false`면 실결제만, 생략하면 전부예요");
+const pageQuery = { page: z.string().optional().describe("페이지 번호 (1부터, 기본 1)") };
+/**
+* `GET /v1/orders` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 검증 규칙은 서버가 적용한다:
+* `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜 형식 오류 400 `INVALID_PARAMETER`, 31일 초과 400 `RANGE_TOO_WIDE`,
+* `testPayment`가 `true`·`false`가 아니면 400 `INVALID_PARAMETER`
+*/
+const orderListQuerySchema = z.object({
+	orderedFrom: z.string().describe("조회 시작 시각 (ISO 8601 날짜 또는 일시, 포함). 필수"),
+	orderedTo: z.string().optional().describe("조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 31일"),
+	status: orderItemStatusSchema.optional().describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),
+	keyword: z.string().optional().describe("주문번호(일치)·주문자명·수령인명(포함) 검색"),
+	testPayment: testPaymentQuery,
+	...pageQuery,
+	size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)")
+});
+/**
+* `GET /v1/order-items` 쿼리 — OpenAPI 문서용 형태. `lastChangedFrom` 누락 400 `MISSING_PARAMETER`, 형식 오류 400
+* `INVALID_PARAMETER`, 24시간 초과 400 `RANGE_TOO_WIDE`, `testPayment` 값 오류 400 `INVALID_PARAMETER`
+*/
+const orderItemListQuerySchema = z.object({
+	lastChangedFrom: z.string().describe("마지막 변경 시각 조회 시작 (ISO 8601, 포함). 필수"),
+	lastChangedTo: z.string().optional().describe("마지막 변경 시각 조회 끝 (ISO 8601, 포함). 생략하면 시작부터 24시간. 기간은 최대 24시간"),
+	lastChangedType: changeTypeSchema.optional().describe("마지막 변경 유형 필터"),
+	testPayment: testPaymentQuery,
+	...pageQuery,
+	size: z.string().optional().describe("페이지 크기 (기본 100, 최대 300)")
+});
+const deliveryMethodSchema = z.enum([
+	"COURIER",
+	"DIRECT",
+	"QUICK",
+	"NOTHING"
+]);
+const dispatchRequestSchema = z.object({
+	deliveryMethod: deliveryMethodSchema,
+	carrierCode: z.string().optional(),
+	trackingNumber: z.string().optional(),
+	dispatchedAt: z.string().optional()
+}).refine((value) => value.deliveryMethod === "DIRECT" || value.deliveryMethod === "NOTHING" ? true : !!value.carrierCode && !!value.trackingNumber, { message: "COURIER/QUICK 발송은 carrierCode와 trackingNumber가 필수입니다" });
+const deliveryInfoSchema = z.object({
+	orderItemId: z.string(),
+	deliveryMethod: deliveryMethodSchema,
+	carrierCode: z.string().nullable(),
+	carrierName: z.string().nullable(),
+	trackingNumber: z.string().nullable(),
+	trackingUrl: z.url().nullable(),
+	status: z.enum([
+		"DISPATCHED",
+		"DELIVERING",
+		"DELIVERED"
+	]),
+	dispatchedAt: z.string(),
+	deliveredAt: z.string().nullable()
+});
+const carrierSchema = z.object({
+	carrierCode: z.string(),
+	name: z.string(),
+	trackingUrlTemplate: z.string()
+});
+const holdOrderItemRequestSchema = z.object({
+	reason: z.enum([
+		"OUT_OF_STOCK",
+		"CUSTOMER_REQUEST",
+		"CUSTOMS",
+		"ETC"
+	]),
+	detail: z.string().max(500).optional(),
+	expectedDispatchDate: z.string()
+});
+const cancelBySellerRequestSchema = z.object({
+	reason: z.enum([
+		"OUT_OF_STOCK",
+		"PRICE_ERROR",
+		"DELIVERY_IMPOSSIBLE",
+		"ETC"
+	]),
+	detail: z.string().max(500).optional()
+});
+//#endregion
+//#region src/schemas/payment.ts
+/**
+* 스토어 결제(PG) 설정과 매출 리포트 계약.
+*
+* PG는 셀러가 직접 계약한다. 자격 증명은 스토어별로 저장되고, 비밀 값(시크릿 키·API Secret·
+* 웹훅 시크릿)은 저장 후 다시 조회할 수 없다. 응답에는 앞 4자리 마스킹만 나온다. 공개 값
+* (클라이언트 키·Store ID·채널 키)은 원래 브라우저 결제창에 노출되는 값이라 그대로 돌려준다.
+*/
+const pgProviderSchema = z.enum(["tosspayments", "portone"]).describe("PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2)");
+const pgPaymentMethodSchema = z.enum([
+	"CARD",
+	"BANK_TRANSFER",
+	"VIRTUAL_ACCOUNT",
+	"MOBILE",
+	"EASY_PAY"
+]).describe("결제수단 (스토어프론트 결제 요청의 `paymentMethod`와 같은 값)");
+const paymentRoutingModeSchema = z.enum(["PRIORITY_DISPLAY", "AUTO_FAILOVER"]).describe("PG가 둘 이상 사용 중일 때의 라우팅 방식. `PRIORITY_DISPLAY`=결제창에 사용 중인 PG를 모두 보여 주고 1순위를 기본 선택, `AUTO_FAILOVER`=1순위로 결제창을 열고, 결제창을 띄우기 전 장애(PG 준비 실패)일 때만 다음 순위로 자동 전환");
+const effectivePaymentRoutingModeSchema = z.enum([
+	"NONE",
+	"SINGLE",
+	"PRIORITY_DISPLAY",
+	"AUTO_FAILOVER"
+]).describe("실제로 적용되는 라우팅. 사용 중인 PG가 0개면 `NONE`(결제 불가), 1개면 `SINGLE`, 2개 이상이면 `routingMode` 값");
+const pgEnvironmentSchema = z.enum(["TEST", "LIVE"]).describe("PG 결제 환경. `TEST`=PG 샌드박스(테스트 키, 실제로 돈이 오가지 않음), `LIVE`=실결제(운영 키)");
+const pgVerificationResultSchema = z.enum(["SUCCESS", "FAILED"]).describe("연결 테스트 결과");
+/** 비밀 값 입력 — 저장 후 다시 조회할 수 없다 */
+const secretInput = () => z.string().trim().min(8).max(512);
+/**
+* 토스페이먼츠 결제위젯 키 접두사. 결제창은 API 개별 연동(`*_ck_`·`*_sk_`)만 쓴다. 위젯 키는 결제창 SDK가
+* `NOT_SUPPORTED_WIDGET_KEY`로, 서버 API가 404 `NOT_FOUND_MERCHANT`로 거부하므로 저장 전에 막는다.
+* 요청 스키마·api 어댑터·콘솔 폼이 같은 상수를 쓴다(원천). `g` 플래그가 없어 `.test()`가 상태를 갖지 않는다.
+*/
+const TOSS_WIDGET_CLIENT_KEY_PATTERN = /^(test|live)_gck_/;
+/** 토스페이먼츠 결제위젯 시크릿 키 접두사. {@link TOSS_WIDGET_CLIENT_KEY_PATTERN} 참고 */
+const TOSS_WIDGET_SECRET_KEY_PATTERN = /^(test|live)_gsk_/;
+/** 결제위젯 키를 거부할 때의 필드 메시지 */
+const TOSS_WIDGET_KEY_MESSAGE = "결제위젯 키가 아니라 API 개별 연동 키를 입력해주세요";
+const tossPaymentsCredentialsInputSchema = z.object({
+	clientKey: z.string().trim().min(8).max(200).describe("클라이언트 키 (`test_ck_…`/`live_ck_…`). 공개 값 — 결제창에서 쓰인다"),
+	secretKey: secretInput().optional().describe("시크릿 키 (`test_sk_…`/`live_sk_…`). 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+	webhookSecret: secretInput().nullable().optional().describe("웹훅 서명 검증용 보안 키. 비밀 값. 생략하면 기존 값 유지, null이면 삭제")
+}).superRefine((value, ctx) => {
+	if (TOSS_WIDGET_CLIENT_KEY_PATTERN.test(value.clientKey)) ctx.addIssue({
+		code: "custom",
+		path: ["clientKey"],
+		message: TOSS_WIDGET_KEY_MESSAGE
+	});
+	if (value.secretKey !== void 0 && TOSS_WIDGET_SECRET_KEY_PATTERN.test(value.secretKey)) ctx.addIssue({
+		code: "custom",
+		path: ["secretKey"],
+		message: TOSS_WIDGET_KEY_MESSAGE
+	});
+});
+/** 포트원 채널 목록 최소 개수. 결제수단을 받으려면 채널이 하나는 있어야 한다 */
+const PORTONE_MIN_CHANNELS = 1;
+/** 포트원 채널 목록 최대 개수 */
+const PORTONE_MAX_CHANNELS = 20;
+/** 포트원 채널 표시 이름 최대 길이 */
+const PORTONE_CHANNEL_NAME_MAX_LENGTH = 50;
+const portOneChannelSchema = z.object({
+	channelKey: z.string().trim().min(8).max(200).describe("포트원 콘솔 [연동 정보] > [채널 관리]의 채널 키. 공개 값"),
+	name: z.string().trim().max(50).nullable().optional().describe("채널 표시 이름 (예: 카드 전용)"),
+	payMethods: z.array(pgPaymentMethodSchema).min(1).max(pgPaymentMethodSchema.options.length).describe("이 채널로 받을 결제수단. 결제수단마다 먼저 나열된 채널이 쓰인다")
+});
+const portOneCredentialsInputSchema = z.object({
+	storeId: z.string().trim().min(8).max(200).describe("포트원 Store ID (`store-…`). 공개 값"),
+	channels: z.array(portOneChannelSchema).min(1).max(20).describe("채널 목록. 포트원 V2는 PG·결제수단별로 채널을 따로 추가하므로 여러 개를 등록할 수 있다"),
+	apiSecret: secretInput().optional().describe("V2 API Secret. 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+	webhookSecret: secretInput().nullable().optional().describe("웹훅 서명 검증용 시크릿. 비밀 값. 생략하면 기존 값 유지, null이면 삭제")
+});
+const upsertEnvironment = () => pgEnvironmentSchema.describe("저장할 자격 증명 세트. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 세트를 따로 둔다. 어느 세트로 결제할지는 이 값이 아니라 샌드박스 스위치(`sandboxMode`)가 정한다");
+const upsertTossPaymentsProviderRequestSchema = z.object({
+	environment: upsertEnvironment(),
+	credentials: tossPaymentsCredentialsInputSchema
+});
+const upsertPortOneProviderRequestSchema = z.object({
+	environment: upsertEnvironment(),
+	credentials: portOneCredentialsInputSchema
+});
+const updatePaymentProviderRequestSchema = z.object({
+	enabled: z.boolean().optional().describe("사용 여부. 켜려면 활성 환경(샌드박스면 TEST, 아니면 LIVE) 자격 증명이 모두 저장돼 있어야 한다(`PAYMENT_PROVIDER_INCOMPLETE`)"),
+	sandboxMode: z.boolean().optional().describe("샌드박스 스위치. `true`면 새 결제에 TEST 세트를 쓴다(항상 허용). `false`(라이브 전환)는 라이브 개방 조건을 모두 충족해야 한다(`LIVE_GATE_NOT_MET`)")
+}).refine((body) => body.enabled !== void 0 || body.sandboxMode !== void 0, { message: "enabled 또는 sandboxMode 중 하나는 보내야 해요" });
+const verifyPaymentProviderRequestSchema = z.object({ environment: pgEnvironmentSchema.optional().describe("연결 테스트할 자격 증명 세트. 생략하면 활성 환경(샌드박스면 TEST, 아니면 LIVE)") });
+const updatePaymentSettingsRequestSchema = z.object({
+	routingMode: paymentRoutingModeSchema,
+	priority: z.array(pgProviderSchema).min(1).max(50).describe("PG 우선순위(앞이 1순위). 연결된 PG 수만큼 **모두 한 번씩** 나열한다(길이 상한 50은 안전장치다). 빠지거나 중복되거나 연결되지 않은 PG가 있으면 `INVALID_PRIORITY`")
+});
+const maskedSecretSchema = z.object({
+	field: z.string().describe("비밀 필드 이름 (`secretKey`·`apiSecret`·`webhookSecret`)"),
+	configured: z.boolean().describe("값이 저장돼 있는가"),
+	masked: z.string().nullable().describe("앞 4자리만 남긴 마스킹 값 (예: `test****`). 저장되지 않았으면 null")
+});
+const publicConfigSchema = z.union([z.object({ clientKey: z.string() }), z.object({
+	storeId: z.string(),
+	channels: z.array(portOneChannelSchema)
+})]);
+const verificationSchema = z.object({
+	result: pgVerificationResultSchema,
+	message: z.string().nullable(),
+	checkedAt: z.string()
+});
+const paymentCredentialSetSchema = z.object({
+	environment: pgEnvironmentSchema,
+	publicConfig: publicConfigSchema.describe("공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`"),
+	secrets: z.array(maskedSecretSchema).describe("비밀 값의 저장 여부와 마스킹. 평문은 어떤 응답에도 나오지 않는다"),
+	lastVerification: verificationSchema.nullable().describe("이 세트의 마지막 연결 테스트 결과. 세트를 바꾸면 초기화된다"),
+	updatedAt: z.string()
+});
+const liveGateConditionCodeSchema = z.enum([
+	"TEST_CONNECTION",
+	"SANDBOX_PAYMENT",
+	"SANDBOX_REFUND",
+	"LIVE_CONNECTION",
+	"PLATFORM_LIVE_ENABLED"
+]).describe("라이브 개방 조건. `TEST_CONNECTION`=TEST 세트 연결 테스트 성공, `SANDBOX_PAYMENT`=현재 TEST 세트로 샌드박스 결제 1건 승인, `SANDBOX_REFUND`=그 샌드박스 결제의 환불 1건 성공, `LIVE_CONNECTION`=LIVE 세트 연결 테스트 성공, `PLATFORM_LIVE_ENABLED`=플랫폼이 실결제를 열어 둠");
+const liveGateConditionSchema = z.object({
+	code: liveGateConditionCodeSchema,
+	met: z.boolean().describe("충족 여부"),
+	message: z.string().describe("조건 설명 또는 미충족 사유")
+});
+const liveGateSchema = z.object({
+	status: z.enum(["LOCKED", "OPEN"]).describe("`OPEN`=조건을 모두 충족해 샌드박스를 끌 수 있다, `LOCKED`=아직 끌 수 없다"),
+	conditions: z.array(liveGateConditionSchema),
+	openedAt: z.string().nullable().describe("마지막으로 라이브로 전환한 시각. 없으면 null")
+});
+/**
+* 409 `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의 `ApiError.details` 형태.
+* 응답 파싱용이라 관대하다 — 알 수 없는 키는 버리고, 형태가 다르면 safeParse 실패로 처리한다.
+*/
+const liveGateErrorDetailsSchema = z.object({ conditions: z.array(liveGateConditionSchema).describe("라이브 개방 조건별 충족 여부 (순서 고정)") });
+const paymentProviderSchema = z.object({
+	provider: pgProviderSchema,
+	displayName: z.string().describe("표시 이름 (토스페이먼츠·포트원)"),
+	connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
+	enabled: z.boolean().describe("결제에 사용 중인가"),
+	priority: z.number().int().nullable().describe("우선순위 (1이 가장 높다). 연결되지 않았으면 null"),
+	environment: pgEnvironmentSchema.nullable().describe("새 결제에 쓰는 환경(활성 환경). 샌드박스 스위치가 켜져 있으면 `TEST`, 꺼져 있으면 `LIVE`. 연결되지 않았으면 null"),
+	publicConfig: publicConfigSchema.nullable().describe("활성 환경 세트의 공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`. 활성 세트가 없으면 null"),
+	secrets: z.array(maskedSecretSchema).describe("활성 환경 세트의 비밀 값 저장 여부와 마스킹. 평문은 어떤 응답에도 나오지 않는다"),
+	lastVerification: verificationSchema.nullable().describe("활성 환경 세트의 마지막 연결 테스트 결과. 세트를 바꾸면 초기화된다"),
+	updatedAt: z.string().nullable(),
+	sandboxMode: z.boolean().describe("샌드박스 스위치. `true`면 새 결제에 TEST 세트를 쓴다(실제로 돈이 오가지 않는다). 연결되지 않았으면 true"),
+	credentialSets: z.object({
+		TEST: paymentCredentialSetSchema.nullable(),
+		LIVE: paymentCredentialSetSchema.nullable()
+	}).describe("환경별 자격 증명 세트. 등록되지 않은 세트는 null"),
+	liveGate: liveGateSchema.describe("라이브 개방 조건. 조건을 모두 충족해야 샌드박스를 끌 수 있다"),
+	retiredCredentialCount: z.number().int().describe("보관된(가맹점 교체·연결 해제로 새 결제에 더 쓰이지 않는) 자격 증명 수. 그 가맹점으로 받은 결제의 환불·대사에 계속 쓰인다"),
+	routingExclusion: z.string().nullable().optional().default(null).describe("지금 새 결제의 후보가 아닌 사유. 후보면 null. 판정 원천은 서버 라우팅이다(콘솔이 다시 계산하지 않는다). 후보가 아닌 PG에는 항상 사유 코드를 붙인다(연결 안 된 PG 포함) — 모든 PG는 `candidates`에 있거나 이 값이 null이 아니다. 현재 값: `NOT_CONNECTED`(연결 안 됨) · `DISABLED`(사용 중지) · `CREDENTIAL_MISSING`(활성 환경 자격 증명 없음) · `SANDBOX_IN_LIVE_STORE`(다른 PG가 라이브라 이 샌드박스 PG는 실구매자 결제에 쓰지 않음) · `PLATFORM_BLOCKED`(플랫폼이 실결제를 막음) · `MODE_MISMATCH`(라이브를 연 서버 모드와 현재 모드가 다름). 값이 추가될 수 있어 문자열로 받는다 — 모르는 값은 후보 아님으로 다룬다. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(null)으로 읽는다")
+});
+/**
+* `PaymentProvider.routingExclusion`의 현재 값 — 응답 스키마는 서버가 사유를 추가해도 파싱이 깨지지 않게 문자열로 받는다.
+* 화면 문구 분기는 이 목록으로 하고, 모르는 값은 "후보 아님"으로 다룬다.
+*/
+const PAYMENT_ROUTING_EXCLUSION_CODES = [
+	"NOT_CONNECTED",
+	"DISABLED",
+	"CREDENTIAL_MISSING",
+	"SANDBOX_IN_LIVE_STORE",
+	"PLATFORM_BLOCKED",
+	"MODE_MISMATCH"
+];
+const paymentSettingsSchema = z.object({
+	routingMode: paymentRoutingModeSchema.describe("저장된 라우팅 방식 (기본 `AUTO_FAILOVER`). PG가 하나뿐이면 무시된다"),
+	effectiveRoutingMode: effectivePaymentRoutingModeSchema,
+	providers: z.array(paymentProviderSchema).describe("지원하는 모든 PG. 연결된 것은 우선순위순, 연결되지 않은 것은 뒤에 온다"),
+	environment: pgEnvironmentSchema.nullable().optional().default(null).describe("지금 결제를 시작하면 쓰는 결제 환경. 사용 가능한 PG 중 하나라도 라이브면 `LIVE`(샌드박스 PG는 제외), 아니면 `TEST`. 사용 가능한 PG가 없으면 null. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(null)으로 읽는다"),
+	candidates: z.array(z.string()).optional().default(() => []).describe("지금 결제를 시작하면 쓰는 PG, 우선순위순(`tosspayments`·`portone`). 비어 있으면 구매자가 결제할 수 없다. 빠진 PG의 사유는 `providers[].routingExclusion` — 후보가 아닌 PG에는 항상 사유 코드를 붙인다. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(빈 배열)으로 읽는다")
+});
+const paymentProviderVerificationSchema = z.object({
+	provider: pgProviderSchema,
+	environment: pgEnvironmentSchema.describe("연결 테스트한 자격 증명 세트"),
+	result: pgVerificationResultSchema,
+	message: z.string().nullable().describe("실패 사유 또는 참고 메시지"),
+	checkedAt: z.string()
+});
+const salesReportGroupBySchema = z.enum([
+	"DAY",
+	"PROVIDER",
+	"METHOD",
+	"PROVIDER_METHOD"
+]).describe("행 집계 기준. 기본 `DAY`");
+const reportDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "날짜 형식은 YYYY-MM-DD 입니다");
+const salesReportQuerySchema = z.object({
+	from: reportDate.describe("시작일 (YYYY-MM-DD, Asia/Seoul 기준, 포함)"),
+	to: reportDate.describe("종료일 (YYYY-MM-DD, 포함). from부터 최대 92일"),
+	provider: pgProviderSchema.optional().describe("PG 필터"),
+	method: pgPaymentMethodSchema.optional().describe("결제수단 필터 — **실제 결제수단**(PG가 보고한 수단, 모르면 요청 수단) 기준. 결제창에서 결제수단이 바뀔 수 있다(카드 결제창의 간편결제 탭 등). 관리 주문 API의 method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다"),
+	groupBy: salesReportGroupBySchema.optional(),
+	includeTest: z.enum(["true", "false"]).optional().describe("테스트 결제(샌드박스 결제) 포함 여부. 기본 `false` — 테스트 결제의 승인·환불은 집계에서 빠진다")
+});
+const salesTotalsSchema = z.object({
+	paymentCount: z.number().int().describe("승인 건수"),
+	paymentAmount: z.number().int().describe("승인 금액 합계"),
+	refundCount: z.number().int().describe("환불(취소) 건수. 부분 취소도 1건"),
+	refundAmount: z.number().int().describe("환불 금액 합계"),
+	netAmount: z.number().int().describe("순매출 = 승인 금액 - 환불 금액"),
+	pgFeeAmount: z.number().int().nullable().describe("PG 수수료 (참고용). PG에서 확정 값을 받지 못하면 null")
+});
+const salesReportRowSchema = salesTotalsSchema.extend({
+	date: z.string().nullable().describe("일자 (YYYY-MM-DD, Asia/Seoul). groupBy=DAY일 때만 값"),
+	provider: pgProviderSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
+	method: pgPaymentMethodSchema.nullable().describe("실제 결제수단(PG가 보고한 수단, 모르면 요청 수단). groupBy에 METHOD가 포함될 때만 값. 관리 주문 API의 method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다")
+});
+const salesReportSchema = z.object({
+	from: z.string(),
+	to: z.string(),
+	timezone: z.literal("Asia/Seoul"),
+	currency: z.literal("KRW"),
+	groupBy: salesReportGroupBySchema,
+	provider: pgProviderSchema.nullable().describe("적용된 PG 필터"),
+	method: pgPaymentMethodSchema.nullable().describe("적용된 결제수단 필터"),
+	includeTest: z.boolean().describe("테스트 결제(샌드박스 결제)를 집계에 포함했는가"),
+	summary: salesTotalsSchema.describe("기간 전체 합계"),
+	rows: z.array(salesReportRowSchema).describe("집계 행. 활동이 없는 날짜·PG는 생략된다")
+});
+/**
+* 결제 내역 — 결제 건(세션) 단위 공개 상태. 주문 단위 상태와 다르다.
+* - `APPROVED`: 승인됐고 환불이 없다
+* - `PARTIALLY_REFUNDED`·`REFUNDED`: 승인 뒤 일부·전액을 환불했다
+* - `PENDING`: 승인 결과를 아직 확정하지 못했다(대사 잡이 확정한다)
+* - `FAILED`: 승인되지 않고 끝났다(거절·준비 장애·구매자 취소·만료)
+*/
+const paymentRecordStatusSchema = z.enum([
+	"APPROVED",
+	"PARTIALLY_REFUNDED",
+	"REFUNDED",
+	"PENDING",
+	"FAILED"
+]);
+const paymentAttemptStatusSchema = z.string().describe("시도 상태 — ready·approving·approved·unknown·declined·prepare_failed·canceled·failed·abandoned·voided. 새 값이 추가될 수 있으니 모르는 값은 '진행 중이 아닌 시도'로 다룬다");
+const paymentRecordSchema = z.object({
+	paymentId: z.string().describe("결제 건 id. 상세 조회 키"),
+	orderId: z.string().nullable().describe("승인돼 만들어진 주문. 승인 전에 끝난 결제는 null"),
+	orderName: z.string().describe("주문명 (예: 무선 이어폰 프로 외 1건)"),
+	customerName: z.string().describe("구매자명"),
+	status: paymentRecordStatusSchema,
+	amount: z.number().int().describe("결제 금액"),
+	refundedAmount: z.number().int().describe("환불 완료 금액 합계. 실패한 환불은 빼고 센다"),
+	provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
+	method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
+	environment: pgEnvironmentSchema.nullable().describe("결제 환경"),
+	testPayment: z.boolean().describe("샌드박스 결제인가"),
+	pgTransactionId: z.string().nullable().describe("PG 거래 id (토스 paymentKey, 포트원 txId)"),
+	attemptId: z.string().nullable().describe("PG에 보낸 주문번호 = 시도 id"),
+	attemptCount: z.number().int().describe("시도 횟수"),
+	failCode: z.string().nullable().describe("실패 코드. 실패로 끝난 결제만"),
+	failMessage: z.string().nullable().describe("실패 사유"),
+	paidAt: z.string().nullable().describe("승인 시각 (ISO 8601)"),
+	createdAt: z.string().describe("결제 시작 시각 (ISO 8601)")
+});
+const paymentRecordPageSchema = pageSchema(paymentRecordSchema);
+const paymentAttemptRecordSchema = z.object({
+	attemptId: z.string(),
+	sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
+	provider: pgProviderSchema,
+	status: paymentAttemptStatusSchema,
+	method: pgPaymentMethodSchema.describe("주문서에서 고른 결제수단"),
+	approvedMethod: pgPaymentMethodSchema.nullable().describe("PG가 보고한 실제 결제수단"),
+	amount: z.number().int(),
+	environment: pgEnvironmentSchema,
+	pgTransactionId: z.string().nullable(),
+	failCode: z.string().nullable(),
+	failMessage: z.string().nullable(),
+	createdAt: z.string(),
+	updatedAt: z.string()
+});
+const paymentRefundRecordSchema = z.object({
+	refundId: z.string(),
+	amount: z.number().int(),
+	reason: z.string().describe("환불 사유 코드"),
+	kind: z.string().describe("환불 원인 — SELLER_CANCEL·CLAIM·COMPENSATION·DUPLICATE. 새 값이 추가될 수 있다"),
+	status: z.string().describe("SUCCEEDED·FAILED"),
+	failMessage: z.string().nullable(),
+	requestedAt: z.string(),
+	completedAt: z.string().nullable()
+});
+const paymentRecordDetailSchema = paymentRecordSchema.extend({
+	refundableAmount: z.number().int().describe("환불 가능 잔액 = 승인 금액 - 환불 완료 금액"),
+	merchantId: z.string().nullable().describe("가맹점 식별자 지문 (토스 clientKey, 포트원 Store ID). 비밀 값은 없다"),
+	attempts: z.array(paymentAttemptRecordSchema).describe("시도 이력. 순번 오름차순"),
+	refunds: z.array(paymentRefundRecordSchema).describe("환불 이력. 실패한 요청도 남는다")
+});
+/** `GET /v1/payments` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+const paymentListQuerySchema = z.object({
+	from: z.string().optional().describe("조회 시작 시각 (ISO 8601, 포함). 생략하면 최근 30일"),
+	to: z.string().optional().describe("조회 끝 시각 (ISO 8601, 포함). 기간은 최대 92일"),
+	status: z.string().optional().describe("결제 상태 필터 (PaymentRecordStatus)"),
+	provider: z.string().optional().describe("PG 필터"),
+	method: z.string().optional().describe("실제 결제수단 필터"),
+	keyword: z.string().optional().describe("결제 id·주문번호·PG 거래 id·시도 id(일치), 구매자명(포함)"),
+	includeTest: z.string().optional().describe("테스트 결제 포함 여부 (`true`·`false`. 기본 false — 실결제만)"),
+	page: z.string().optional().describe("페이지 번호 (1부터)"),
+	size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)")
+});
+//#endregion
+//#region src/schemas/product.ts
+const productStatusSchema = z.enum([
+	"SALE",
+	"SUSPENDED",
+	"OUT_OF_STOCK",
+	"CLOSED"
+]);
+const deliveryTypeSchema = z.enum([
+	"FREE",
+	"PAID",
+	"CONDITIONAL_FREE"
+]);
+const productSummarySchema = z.object({
+	productId: z.string(),
+	name: z.string(),
+	status: productStatusSchema,
+	salePrice: z.number().int(),
+	discountedPrice: z.number().int().nullable(),
+	/** usable variant 재고 합계 (서버 계산) */
+	stockQuantity: z.number().int(),
+	categoryId: z.string().nullable(),
+	thumbnailUrl: z.url().optional(),
+	/** optionGroups.length > 0 */
+	hasOptions: z.boolean(),
+	updatedAt: z.string()
+});
+/** 옵션 축(그룹)이 가지는 값 하나 — 예: 축 "색상"의 값 "블랙" */
+const optionValueSchema = z.object({
+	valueId: z.string(),
+	name: z.string(),
+	sortOrder: z.number().int()
+});
+/** 옵션 축(그룹) — 예: "색상", "사이즈" */
+const optionGroupSchema = z.object({
+	groupId: z.string(),
+	name: z.string(),
+	sortOrder: z.number().int(),
+	values: z.array(optionValueSchema)
+});
+/**
+* 판매 단위(SKU). variantId는 기존 optionId 값 공간을 승계하므로
+* 카트·주문·리뷰·클레임의 optionId가 곧 variantId다.
+*/
+const productVariantSchema = z.object({
+	variantId: z.string(),
+	/** 축 sortOrder 순서와 1:1 대응. 옵션 없는 상품은 [] */
+	valueIds: z.array(z.string()),
+	/** 값 이름을 " / "로 이은 파생 표시명. 옵션 없으면 "" */
+	name: z.string(),
+	additionalPrice: z.number().int(),
+	stockQuantity: z.number().int(),
+	sku: z.string().nullable(),
+	barcode: z.string().nullable(),
+	costPrice: z.number().int().nullable(),
+	weightGram: z.number().int().nullable(),
+	sellerCode: z.string().nullable(),
+	usable: z.boolean()
+});
+const productSchema = productSummarySchema.extend({
+	description: z.string().optional(),
+	/**
+	* 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
+	* 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
+	*/
+	descriptionJson: z.string().nullable().optional(),
+	originalPrice: z.number().int().nullable().optional(),
+	images: z.array(z.url()).optional(),
+	attributes: z.array(z.object({
+		attributeId: z.string(),
+		value: z.string()
+	})).optional(),
+	optionGroups: z.array(optionGroupSchema),
+	/** 모든 상품이 최소 1개 variant를 갖는다 (옵션 없으면 default variant 1개) */
+	variants: z.array(productVariantSchema),
+	deliveryType: deliveryTypeSchema.optional(),
+	deliveryFee: z.number().int().optional(),
+	conditionalFreeAmount: z.number().int().nullable().optional(),
+	returnFee: z.number().int().optional(),
+	exchangeFee: z.number().int().optional(),
+	shippingAddressId: z.string().nullable().optional(),
+	returnAddressId: z.string().nullable().optional(),
+	createdAt: z.string().optional()
+});
+/** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
+const MAX_OPTION_GROUPS = 3;
+/** 축 하나가 가질 수 있는 값의 최대 개수 */
+const MAX_VALUES_PER_GROUP = 100;
+/** 상품 하나가 가질 수 있는 variant(SKU) 최대 개수 */
+const MAX_VARIANTS = 500;
+/**
+* 식별 코드 — 빈 문자열·공백만 있는 값은 거부한다.
+* `""`를 통과시키면 서버 중복 사전 검사(falsy skip)와 DB partial unique
+* (`WHERE ... is not null`)의 판정이 갈려 409 대신 500이 나간다.
+*/
+const codeSchema = z.string().trim().min(1).max(64);
+const optionValueRequestSchema = z.object({
+	/** 전달 시 기존 값 행을 유지(UPDATE). 생략하면 신규 발급 */
+	valueId: z.string().optional(),
+	name: z.string().min(1).max(50)
+});
+const optionGroupRequestSchema = z.object({
+	/** 전달 시 기존 축 행을 유지(UPDATE). 생략하면 신규 발급 */
+	groupId: z.string().optional(),
+	name: z.string().min(1).max(50),
+	values: z.array(optionValueRequestSchema).min(1).max(100)
+});
+const productVariantRequestSchema = z.object({
+	/** 기존 variant 유지 시 전달. 생략하면 신규 생성 */
+	variantId: z.string().optional(),
+	/** optionGroups 순서대로 각 축에서 고른 값 이름. 서버가 이름 → valueId를 해석한다 */
+	valueNames: z.array(z.string()).default([]),
+	additionalPrice: z.number().int().default(0),
+	/**
+	* 생략 = 기존 재고 유지 (신규 variant는 0).
+	* 구조 교체(PUT)가 폼 로드 시점의 재고를 되쓰지 않게 하는 옵트인 필드다 —
+	* 재고만 바꿀 때는 PATCH /products/{id}/variants/{variantId}/stock을 쓴다.
+	*/
+	stockQuantity: z.number().int().min(0).optional(),
+	sku: codeSchema.optional(),
+	barcode: codeSchema.optional(),
+	costPrice: z.number().int().min(0).optional(),
+	weightGram: z.number().int().min(0).optional(),
+	sellerCode: codeSchema.optional(),
+	usable: z.boolean().default(true)
+});
+/** 축 × 값 → variant 전체 교체 요청 (PUT /products/{productId}/options) */
+const optionModelRequestSchema = z.object({
+	optionGroups: z.array(optionGroupRequestSchema).max(3).default([]),
+	variants: z.array(productVariantRequestSchema).min(1).max(500)
+});
+/** GET /products/{productId}/options 응답 */
+const optionModelSchema = z.object({
+	optionGroups: z.array(optionGroupSchema),
+	variants: z.array(productVariantSchema)
+});
+/**
+* 재고 변경 택일 위반 문구 — SDK `.refine`과 서버 DomainException이 공유하는 단일 원천.
+* 경로에 따라 셀러가 다른 문구를 받지 않게 한다.
+*/
+const VARIANT_STOCK_EXCLUSIVE_MESSAGE = "stockQuantity 또는 adjustment 중 하나만 전달해야 합니다";
+/**
+* variant 재고 변경 요청 — 절대값(`stockQuantity`) 또는 증감(`adjustment`) 택일.
+* 서버도 같은 규칙을 400 VALIDATION_FAILED로 검증한다(이중 방어).
+*/
+const variantStockRequestSchema = z.object({
+	stockQuantity: z.number().int().min(0).optional(),
+	adjustment: z.number().int().optional()
+}).refine((v) => v.stockQuantity !== void 0 !== (v.adjustment !== void 0), { message: VARIANT_STOCK_EXCLUSIVE_MESSAGE });
+/** PATCH /products/{productId}/variants/{variantId}/stock 응답 */
+const variantStockSchema = z.object({
+	variantId: z.string(),
+	stockQuantity: z.number().int()
+});
+const productCreateRequestSchema = z.object({
+	name: z.string().min(1).max(100),
+	categoryId: z.string().min(1, "카테고리를 선택해주세요"),
+	salePrice: z.number().int().min(10).multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)"),
+	originalPrice: z.number().int().optional(),
+	description: z.string().optional(),
+	/**
+	* 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
+	* 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
+	*/
+	descriptionJson: z.string().nullable().optional(),
+	images: z.array(z.url()).min(1).max(10).optional(),
+	attributes: z.array(z.object({
+		attributeId: z.string(),
+		value: z.string()
+	})).optional(),
+	deliveryType: deliveryTypeSchema.default("PAID"),
+	deliveryFee: z.number().int().default(0),
+	conditionalFreeAmount: z.number().int().optional(),
+	returnFee: z.number().int().default(0),
+	exchangeFee: z.number().int().default(0),
+	shippingAddressId: z.string().optional(),
+	returnAddressId: z.string().optional()
+}).extend(optionModelRequestSchema.shape);
+const productPatchRequestSchema = z.object({
+	name: z.string().max(100).optional(),
+	salePrice: z.number().int().multipleOf(10).optional(),
+	status: productStatusSchema.optional(),
+	deliveryFee: z.number().int().optional()
+}).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
+const discountSchema = z.object({
+	productId: z.string(),
+	discountType: z.enum(["RATE", "AMOUNT"]),
+	discountValue: z.number().int(),
+	discountedPrice: z.number().int(),
+	startAt: z.string().nullable(),
+	endAt: z.string().nullable()
+});
+const discountRequestSchema = z.object({
+	discountType: z.enum(["RATE", "AMOUNT"]),
+	discountValue: z.number().int().min(1),
+	startAt: z.string().optional(),
+	endAt: z.string().optional()
+});
+//#endregion
+//#region src/schemas/store.ts
+/**
+* 스토어 코드 규칙 — 스토어프론트 API가 테넌트를 가르는 값이다(`X-Store-Code` 헤더).
+* **개설할 때 서버가 랜덤으로 발급하고** 이후 바꿀 수 없다. 이미 나간 링크와 승인된 결제가
+* 이 값에 묶여 있어서 바꾸면 함께 깨진다.
+*
+* 호스트 라벨로도 쓸 수 있게 DNS 라벨 규칙까지 좁힌다. 하이픈으로 시작하거나 끝나는 라벨은 호스트가 될 수 없다.
+*/
+const STORE_CODE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
+/** 플랫폼이 쓰거나 쓸 호스트 이름 — 스토어 코드로 내주지 않는다 */
+const RESERVED_STORE_CODES = [
+	"www",
+	"api",
+	"store",
+	"stores",
+	"checkout",
+	"docs",
+	"admin",
+	"app",
+	"console",
+	"dashboard",
+	"platform",
+	"internal",
+	"auth",
+	"login",
+	"oauth",
+	"account",
+	"accounts",
+	"pay",
+	"payment",
+	"payments",
+	"webhook",
+	"webhooks",
+	"status",
+	"support",
+	"help",
+	"blog",
+	"cdn",
+	"static",
+	"assets",
+	"img",
+	"images",
+	"media",
+	"mail",
+	"smtp",
+	"ftp",
+	"ns",
+	"ns1",
+	"ns2",
+	"mx",
+	"dev",
+	"test",
+	"staging",
+	"stage",
+	"sandbox"
+];
+function isReservedStoreCode(code) {
+	return RESERVED_STORE_CODES.includes(code.toLowerCase());
+}
+const storeCodeSchema = z.string().regex(STORE_CODE_PATTERN, "소문자·숫자·하이픈 3~30자여야 하고 하이픈으로 시작하거나 끝날 수 없어요").refine((code) => !isReservedStoreCode(code), "플랫폼이 쓰는 이름이라 스토어 코드로 쓸 수 없어요");
+const storeSchema = z.object({
+	storeId: z.string(),
+	name: z.string(),
+	storeCode: z.string(),
+	storefrontUrl: z.url(),
+	status: z.enum([
+		"ACTIVE",
+		"SUSPENDED",
+		"CLOSED"
+	]),
+	logoUrl: z.url().nullable(),
+	businessNumber: z.string().nullable(),
+	customerCenterPhone: z.string().nullable(),
+	memberCount: z.number().int(),
+	createdAt: z.string()
+});
+const storeMemberSchema = z.object({
+	userId: z.string(),
+	name: z.string(),
+	email: z.email(),
+	role: storeRoleSchema,
+	joinedAt: z.string(),
+	lastActiveAt: z.string().nullable()
+});
+const invitationSchema = z.object({
+	invitationId: z.string(),
+	email: z.email(),
+	role: z.enum(["ADMIN", "STAFF"]),
+	status: z.enum([
+		"PENDING",
+		"ACCEPTED",
+		"EXPIRED",
+		"CANCELED"
+	]),
+	invitedBy: z.string(),
+	expiresAt: z.string(),
+	createdAt: z.string()
+});
+const addressTypeSchema = z.enum(["SHIPPING", "RETURN"]);
+const sellerAddressSchema = z.object({
+	addressId: z.string(),
+	type: addressTypeSchema,
+	name: z.string(),
+	isDefault: z.boolean(),
+	contactName: z.string(),
+	phone: z.string(),
+	zipCode: z.string(),
+	address1: z.string(),
+	address2: z.string().optional(),
+	createdAt: z.string()
+});
+const sellerAddressRequestSchema = z.object({
+	type: addressTypeSchema,
+	name: z.string().min(1).max(50),
+	contactName: z.string().min(1),
+	phone: z.string().regex(/^01[0-9]{8,9}$/),
+	zipCode: z.string().regex(/^[0-9]{5}$/),
+	address1: z.string().min(1),
+	address2: z.string().optional()
+});
+//#endregion
+//#region src/schemas/upload.ts
+/**
+* 미디어 업로드 자리 발급 — `POST /v1/uploads`.
+*
+* 파일 바이트는 api를 거치지 않는다. 응답의 `uploadUrl`로 클라이언트가 직접 PUT하고,
+* 끝나면 `url`이 공개 주소가 된다. 서버가 객체 키를 정하므로 요청은 파일명만 보낸다
+* (확장자만 쓰이고 이름 자체는 저장되지 않는다).
+*/
+const uploadRequestSchema = z.object({ filename: z.string().min(1).max(255) });
+const uploadTicketSchema = z.object({
+	/** 업로드 완료 후 공개될 주소 */
+	url: z.url(),
+	/** 파일 바이트를 PUT할 presigned URL. 1시간 유효 */
+	uploadUrl: z.url()
+});
+//#endregion
+//#region src/client.ts
+function formBody(fields) {
+	return new URLSearchParams(fields).toString();
+}
+function createStoreClient(options) {
+	const fetchFn = options.fetch ?? globalThis.fetch;
+	const { session } = options;
+	const userTokenSource = options.userToken ?? (session ? () => session.getToken() : void 0);
+	const refresh = options.refresh ?? (session ? () => session.refresh() : void 0);
+	const onUnauthorized = options.onUnauthorized ?? (session ? () => session.clear() : void 0);
+	const storeTokenSource = options.storeToken ?? options.auth?.apiToken;
+	const userHttp = createHttp({
+		baseUrl: options.baseUrl,
+		fetch: fetchFn,
+		headers: () => {
+			const token = resolveToken(userTokenSource);
+			return token ? { authorization: `Bearer ${token}` } : {};
+		},
+		refresh,
+		onUnauthorized
+	});
+	const storeHttp = createHttp({
+		baseUrl: options.baseUrl,
+		fetch: fetchFn,
+		headers: () => {
+			const token = resolveToken(storeTokenSource);
+			const storeId = resolveToken(options.storeId);
+			return {
+				...token ? { authorization: `Bearer ${token}` } : {},
+				...storeId ? { "x-store-id": storeId } : {}
+			};
+		},
+		refresh,
+		onUnauthorized
+	});
+	/** `PATCH /v1/store/payment-providers/{provider}` 단일 구현 — `updateProvider`·`setSandboxMode`가 공유한다 */
+	function updatePaymentProvider(provider, body) {
+		return storeHttp.request("PATCH", path`/store/payment-providers/${pgProviderSchema.parse(provider)}`, paymentProviderSchema, { body: updatePaymentProviderRequestSchema.parse(body) });
+	}
+	function idempotency(key) {
+		return key ? { "idempotency-key": key } : void 0;
+	}
+	function requireSession() {
+		if (!session) throw new Error("oauth 세션 없음 — createStoreSession 필요");
+		return session;
+	}
+	return {
+		/** session의 현재 userToken (session 미배선 시 null — 던지지 않음) */
+		get accessToken() {
+			return session ? session.accessToken : null;
+		},
+		/** session의 현재 refresh 토큰 (session 미배선 시 null — 던지지 않음) */
+		get refreshToken() {
+			return session ? session.refreshToken : null;
+		},
+		/** session.authorize 패스스루 — session 미배선 시 명확한 에러를 던진다 */
+		authorize: (authorizeOptions) => requireSession().authorize(authorizeOptions),
+		/** session.userinfo 패스스루 — session 미배선 시 명확한 에러를 던진다 */
+		userinfo: () => requireSession().userinfo(),
+		auth: {
+			/**
+			* 서버 간 연동(M2M) — client_credentials grant (client_secret_basic).
+			* 클라이언트가 스토어에 바인딩되어 있어 **storeToken이 곧바로 발급**된다.
+			* ⚠ client_secret은 서버 환경에서만 사용할 것 (브라우저 반입 금지)
+			*/
+			async issueStoreTokenByClientCredentials(clientId, clientSecret, scope) {
+				const credentials = base64Utf8(`${clientId}:${clientSecret}`);
+				const response = await fetchFn(`${options.baseUrl}/oauth2/token`, {
+					method: "POST",
+					headers: {
+						"content-type": "application/x-www-form-urlencoded",
+						authorization: `Basic ${credentials}`
+					},
+					body: formBody({
+						grant_type: "client_credentials",
+						...scope ? { scope } : {}
+					})
+				});
+				if (!response.ok) {
+					const body = await response.json().catch(() => null);
+					throw new Error(body?.error_description ?? `토큰 발급 실패 (HTTP ${response.status})`);
+				}
+				return clientCredentialsTokenResponseSchema.parse(unwrapData(await response.json()));
+			},
+			/** 2단계 — 소속 스토어 목록 */
+			listMyStores: () => userHttp.request("GET", "/me/stores", z.array(myStoreSchema)),
+			/** RFC 7009 — token을 폐기한다 (public client는 client_id만 동반) */
+			async revoke(token, clientId) {
+				await fetchFn(`${options.baseUrl}/oauth2/revoke`, {
+					method: "POST",
+					headers: { "content-type": "application/x-www-form-urlencoded" },
+					body: formBody({
+						token,
+						client_id: clientId
+					})
+				});
+			},
+			me: () => userHttp.request("GET", "/me", myAccountSchema)
+		},
+		/** API 토큰(PAT) 관리 — OWNER/ADMIN 전용. 발급된 토큰은 storeToken처럼 Bearer로 사용 */
+		apiTokens: {
+			create: (body) => storeHttp.request("POST", "/store/api-tokens", apiTokenCreatedSchema, { body: apiTokenCreateRequestSchema.parse(body) }),
+			list: () => storeHttp.request("GET", "/store/api-tokens", z.array(apiTokenSchema)),
+			revoke: (tokenId) => storeHttp.requestVoid("DELETE", path`/store/api-tokens/${tokenId}`)
+		},
+		/**
+		* 앱(OAuth 클라이언트) 관리 — OWNER/ADMIN storeToken 전용(PAT·M2M 거부). auth-spec §12, 부록 B-13.
+		* 시크릿 평문은 register·rotateSecret 응답에서만 한 번 노출된다(apiTokens.create와 같은 성격).
+		*/
+		apiClients: {
+			/**
+			* DCR 등록 (RFC 7591) — `POST /v1/oauth2/register`. OAuth 프로토콜 표면이라 응답이 평면 JSON이다.
+			* 등록 오류(`invalid_client_metadata`·`invalid_redirect_uri`)는 ApiError(code=error,
+			* message=error_description)로, Bearer 인증 오류는 엔벨로프 그대로 ApiError로 던진다.
+			*/
+			register: (body) => storeHttp.request("POST", "/oauth2/register", oauthClientRegistrationResponseSchema, { body: oauthClientRegistrationRequestSchema.parse(body) }),
+			list: (params) => storeHttp.request("GET", "/store/api-clients", z.array(apiClientSchema), { query: params }),
+			get: (clientId) => storeHttp.request("GET", path`/store/api-clients/${clientId}`, apiClientSchema),
+			/** confidential 전용. 기존 시크릿은 즉시 무효(유예 없음) */
+			rotateSecret: (clientId) => storeHttp.request("POST", path`/store/api-clients/${clientId}/rotate-secret`, apiClientSecretRotatedSchema),
+			/** REVOKED로 전환(되돌릴 수 없음). 이미 비활성이면 현재 상태를 그대로 돌려준다 */
+			deactivate: (clientId) => storeHttp.request("POST", path`/store/api-clients/${clientId}/deactivate`, apiClientSchema)
+		},
+		/**
+		* 미디어 업로드 — 자리를 받아(`POST /uploads`) 파일 바이트는 호출자가
+		* `uploadUrl`로 직접 PUT한다. 업로드가 끝나면 `url`이 공개 주소가 된다.
+		*/
+		uploads: { create: (body) => storeHttp.request("POST", "/uploads", uploadTicketSchema, { body: uploadRequestSchema.parse(body) }) },
+		products: {
+			list: (params) => storeHttp.request("GET", "/products", pageSchema(productSummarySchema), { query: params }),
+			get: (productId) => storeHttp.request("GET", path`/products/${productId}`, productSchema),
+			create: (body, idempotencyKey) => storeHttp.request("POST", "/products", productSchema, {
+				body: productCreateRequestSchema.parse(body),
+				headers: idempotency(idempotencyKey)
+			}),
+			update: (productId, body) => storeHttp.request("PUT", path`/products/${productId}`, productSchema, { body: productCreateRequestSchema.parse(body) }),
+			patch: (productId, body) => storeHttp.requestVoid("PATCH", path`/products/${productId}`, { body: productPatchRequestSchema.parse(body) }),
+			remove: (productId) => storeHttp.requestVoid("DELETE", path`/products/${productId}`),
+			bulkUpdateStatus: (productIds, status, idempotencyKey) => storeHttp.request("POST", "/products/bulk/status", bulkResultSchema, {
+				body: {
+					productIds,
+					status: productStatusSchema.parse(status)
+				},
+				headers: idempotency(idempotencyKey)
+			}),
+			/** 옵션 축(그룹) × 값 → variant 모델 조회 */
+			getOptionModel: (productId) => storeHttp.request("GET", path`/products/${productId}/options`, optionModelSchema),
+			/**
+			* 옵션 모델 전체 교체 — variants는 valueNames로 축 값을 지목한다.
+			* 응답으로 서버가 배정한 groupId·valueId·신규 variantId가 실린 교체 결과를 돌려준다.
+			*/
+			replaceOptionModel: (productId, body) => storeHttp.request("PUT", path`/products/${productId}/options`, optionModelSchema, { body: optionModelRequestSchema.parse(body) }),
+			/** 재고 변경 — stockQuantity(절대값) 또는 adjustment(증감) 하나만 전달한다 */
+			updateVariantStock: (productId, variantId, body) => storeHttp.request("PATCH", path`/products/${productId}/variants/${variantId}/stock`, variantStockSchema, { body: variantStockRequestSchema.parse(body) }),
+			getDiscount: (productId) => storeHttp.request("GET", path`/products/${productId}/discount`, discountSchema),
+			setDiscount: (productId, body) => storeHttp.request("PUT", path`/products/${productId}/discount`, discountSchema, { body: discountRequestSchema.parse(body) }),
+			removeDiscount: (productId) => storeHttp.requestVoid("DELETE", path`/products/${productId}/discount`)
+		},
+		categories: {
+			list: (params) => storeHttp.request("GET", "/categories", z.array(categorySchema), { query: params }),
+			tree: () => storeHttp.request("GET", "/categories", z.array(categoryTreeNodeSchema), { query: { tree: true } }),
+			search: (q) => storeHttp.request("GET", "/categories", z.array(categorySearchResultSchema), { query: { q } }),
+			get: (categoryId) => storeHttp.request("GET", path`/categories/${categoryId}`, categoryWithPathSchema),
+			listAttributes: (categoryId) => storeHttp.request("GET", path`/categories/${categoryId}/attributes`, z.array(categoryAttributeSchema)),
+			create: (body, idempotencyKey) => storeHttp.request("POST", "/categories", categorySchema, {
+				body: categoryCreateRequestSchema.parse(body),
+				headers: idempotency(idempotencyKey)
+			}),
+			update: (categoryId, body) => storeHttp.request("PATCH", path`/categories/${categoryId}`, categorySchema, { body: categoryPatchRequestSchema.parse(body) }),
+			remove: (categoryId, opts) => storeHttp.requestVoid("DELETE", path`/categories/${categoryId}`, { query: opts?.strategy ? { strategy: opts.strategy } : {} })
+		},
+		orders: {
+			/**
+			* `GET /v1/orders`. `testPayment: "true"`는 테스트 결제(샌드박스) 주문만, `"false"`는 실결제 주문만, 생략하면 전부다.
+			* 그 밖의 값은 400 `INVALID_PARAMETER`. 행마다 `testPayment`가 붙는다.
+			*/
+			list: (params) => storeHttp.request("GET", "/orders", pageSchema(orderSummarySchema), { query: params }),
+			get: (orderId) => storeHttp.request("GET", path`/orders/${orderId}`, orderSchema)
+		},
+		orderItems: {
+			/** `GET /v1/order-items`. `testPayment` 필터는 `orders.list`와 같다 */
+			listChanged: (params) => storeHttp.request("GET", "/order-items", pageSchema(orderItemSchema), { query: params }),
+			confirm: (orderItemId, idempotencyKey) => storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/confirm`, { headers: idempotency(idempotencyKey) }),
+			confirmBulk: (orderItemIds, idempotencyKey) => storeHttp.request("POST", "/order-items/confirm", bulkResultSchema, {
+				body: { orderItemIds },
+				headers: idempotency(idempotencyKey)
+			}),
+			hold: (orderItemId, body) => storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/hold`, { body: holdOrderItemRequestSchema.parse(body) }),
+			releaseHold: (orderItemId) => storeHttp.requestVoid("DELETE", path`/order-items/${orderItemId}/hold`),
+			cancelBySeller: (orderItemId, body, idempotencyKey) => storeHttp.request("POST", path`/order-items/${orderItemId}/cancel`, z.object({
+				orderItemId: z.string(),
+				refundAmount: z.number().int(),
+				refundedAt: z.string()
+			}), {
+				body: cancelBySellerRequestSchema.parse(body),
+				headers: idempotency(idempotencyKey)
+			}),
+			updateMemo: (orderItemId, memo) => storeHttp.requestVoid("PUT", path`/order-items/${orderItemId}/memo`, { body: { memo } }),
+			requestPurchaseDecision: (orderItemId) => storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/purchase-decision/request`),
+			extendPurchaseDecision: (orderItemId) => storeHttp.request("POST", path`/order-items/${orderItemId}/purchase-decision/extend`, z.object({
+				orderItemId: z.string(),
+				autoDecisionDate: z.string(),
+				extendCount: z.number().int().max(2)
+			})),
+			dispatch: (orderItemId, body, idempotencyKey) => storeHttp.request("POST", path`/order-items/${orderItemId}/dispatch`, deliveryInfoSchema, {
+				body: dispatchRequestSchema.parse(body),
+				headers: idempotency(idempotencyKey)
+			}),
+			dispatchBulk: (dispatches, idempotencyKey) => storeHttp.request("POST", "/order-items/dispatch", bulkResultSchema, {
+				body: { dispatches },
+				headers: idempotency(idempotencyKey)
+			}),
+			updateTracking: (orderItemId, carrierCode, trackingNumber) => storeHttp.requestVoid("PUT", path`/order-items/${orderItemId}/dispatch/tracking`, { body: {
+				carrierCode,
+				trackingNumber
+			} }),
+			getDelivery: (orderItemId) => storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryInfoSchema.extend({ trackingEvents: z.array(z.object({
+				status: z.string(),
+				location: z.string(),
+				occurredAt: z.string()
+			})).optional() }))
+		},
+		carriers: { list: () => storeHttp.request("GET", "/carriers", z.array(carrierSchema)) },
+		claims: {
+			list: (params) => storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: params }),
+			get: (claimId) => storeHttp.request("GET", path`/claims/${claimId}`, claimSchema.extend({ histories: z.array(z.object({
+				status: claimStatusSchema,
+				actor: z.enum([
+					"BUYER",
+					"SELLER",
+					"SYSTEM"
+				]),
+				occurredAt: z.string()
+			})).optional() })),
+			approve: (claimId, deductAmount, idempotencyKey) => storeHttp.request("POST", path`/claims/${claimId}/approve`, approveClaimResultSchema, {
+				body: deductAmount !== void 0 ? { deductAmount } : {},
+				headers: idempotency(idempotencyKey)
+			}),
+			reject: (claimId, body) => storeHttp.requestVoid("POST", path`/claims/${claimId}/reject`, { body: rejectClaimRequestSchema.parse(body) }),
+			registerCollect: (claimId, body) => storeHttp.requestVoid("POST", path`/claims/${claimId}/collect`, { body }),
+			completeCollect: (claimId) => storeHttp.requestVoid("POST", path`/claims/${claimId}/collect/complete`),
+			registerRedelivery: (claimId, carrierCode, trackingNumber) => storeHttp.requestVoid("POST", path`/claims/${claimId}/redelivery`, { body: {
+				carrierCode,
+				trackingNumber
+			} }),
+			hold: (claimId, reason) => storeHttp.request("POST", path`/claims/${claimId}/hold`, z.object({
+				claimId: z.string(),
+				holdExpiresAt: z.string()
+			}), { body: { reason } }),
+			releaseHold: (claimId) => storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`)
+		},
+		inquiries: {
+			list: (params) => storeHttp.request("GET", "/inquiries", pageSchema(inquirySchema), { query: params }),
+			get: (inquiryId) => storeHttp.request("GET", path`/inquiries/${inquiryId}`, inquirySchema),
+			answer: (inquiryId, content) => storeHttp.requestVoid("POST", path`/inquiries/${inquiryId}/answer`, { body: { content } }),
+			updateAnswer: (inquiryId, content) => storeHttp.requestVoid("PUT", path`/inquiries/${inquiryId}/answer`, { body: { content } })
+		},
+		customerInquiries: {
+			list: (params) => storeHttp.request("GET", "/customer-inquiries", pageSchema(sellerCustomerInquirySchema), { query: params }),
+			get: (inquiryId) => storeHttp.request("GET", path`/customer-inquiries/${inquiryId}`, sellerCustomerInquirySchema),
+			answer: (inquiryId, content) => storeHttp.requestVoid("POST", path`/customer-inquiries/${inquiryId}/answer`, { body: { content } }),
+			updateAnswer: (inquiryId, content) => storeHttp.requestVoid("PUT", path`/customer-inquiries/${inquiryId}/answer`, { body: { content } })
+		},
+		/**
+		* @deprecated 정산 API는 폐기 예정이다. 새 정산 레코드는 더 이상 만들어지지 않고 기존 레코드 조회만
+		* 유지된다(서버 응답 헤더 `Deprecation: true`). 대체는 {@link salesReport}(`GET /v1/sales-report`)다.
+		*/
+		settlements: {
+			/** @deprecated `salesReport.get`을 쓴다. 기존 정산 레코드 조회만 유지된다 */
+			list: (params) => storeHttp.request("GET", "/settlements", pageSchema(settlementSummarySchema), { query: params }),
+			/** @deprecated `salesReport.get`을 쓴다. 기존 정산 레코드 조회만 유지된다 */
+			get: (settlementId, params) => storeHttp.request("GET", path`/settlements/${settlementId}`, settlementSummarySchema.extend({ details: z.array(settlementDetailSchema).optional() }), { query: params })
+		},
+		/**
+		* 매출 리포트 (정산 API 대체) — 스코프 `settlement:r`. PG 승인 시각 기준 결제, PG 취소 완료 시각 기준
+		* 환불을 Asia/Seoul 날짜로 집계한다. `rows`는 활동 없는 날짜·PG·결제수단을 생략하므로 차트는 빈 구간을 0으로 채운다.
+		*/
+		salesReport: { 
+		/**
+		* `GET /v1/sales-report`. from·to는 양끝 포함, 최대 92일. 테스트 결제(샌드박스)의 승인·환불은 기본 제외이고
+		* `includeTest: "true"`면 포함한다(응답 `includeTest`에 적용 값). 400 `VALIDATION_FAILED`(형식),
+		* 400 `INVALID_PARAMETER`(없는 날짜·to<from), 400 `RANGE_TOO_WIDE`(기간 초과)
+		*/
+get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, { query: salesReportQuerySchema.parse(params) }) },
+		/**
+		* 결제 내역 — 스코프 `settlement:r`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
+		* 결제(카드 거절·결제창 이탈·승인 결과 확인 중)도 그대로 나온다.
+		*/
+		payments: {
+			/**
+			* `GET /v1/payments`. 기간 기준은 결제 시작 시각, 최대 92일이고 생략하면 최근 30일이다. 테스트 결제는
+			* `includeTest: true`일 때만 포함한다. 400 `INVALID_PARAMETER`(시각 형식·to<from), 400 `RANGE_TOO_WIDE`
+			*/
+			list: (params = {}) => storeHttp.request("GET", "/payments", paymentRecordPageSchema, { query: params }),
+			/** `GET /v1/payments/{paymentId}` — 시도·환불 이력 포함. 404 `PAYMENT_NOT_FOUND` */
+			get: (paymentId) => storeHttp.request("GET", path`/payments/${paymentId}`, paymentRecordDetailSchema)
+		},
+		/**
+		* 결제(PG) 설정 — **콘솔 OWNER 전용**. ADMIN·STAFF·PAT·M2M·3rd-party 앱 토큰은 스코프가 있어도
+		* 403 `INSUFFICIENT_ROLE`이다(조회 포함). OWNER 여부는 요청 시점의 스토어 멤버십으로 다시 확인하므로
+		* 양도·강등 직후의 옛 storeToken도 403이다(토큰을 재발급받는다). 비밀 값(시크릿 키·API Secret·웹훅 시크릿)은 요청으로만 보내고
+		* 응답에는 `secrets[].masked`(앞 4자리 마스킹)만 나온다.
+		*/
+		paymentSettings: {
+			/** `GET /v1/store/payment-settings` — 라우팅 모드와 지원 PG 전부(연결된 것은 우선순위순) */
+			get: () => storeHttp.request("GET", "/store/payment-settings", paymentSettingsSchema),
+			/**
+			* `PUT /v1/store/payment-settings` — `priority`에는 연결된 PG를 개수와 무관하게 모두 한 번씩 나열한다
+			* (빠지거나 중복되면 400 `INVALID_PRIORITY`). 진행 중인 결제에는 적용되지 않는다.
+			*/
+			update: (body) => storeHttp.request("PUT", "/store/payment-settings", paymentSettingsSchema, { body: updatePaymentSettingsRequestSchema.parse(body) }),
+			/**
+			* `PUT /v1/store/payment-providers/tosspayments` — 자격 증명 세트 저장. `environment`는 **저장할 세트**(`TEST`·`LIVE`)이고
+			* 결제에 쓰는 세트는 샌드박스 스위치(`setSandboxMode`)가 정한다. 처음 연결하면 `enabled: false`·`sandboxMode: true`로 만들어진다.
+			* 같은 가맹점(`clientKey`)이면 그 세트를 갱신하고, 가맹점이 바뀌면 새 세트를 만들고 이전 세트는 보관한다
+			* (`retiredCredentialCount` +1, 이미 받은 결제의 환불·대사에 계속 쓰인다). `secretKey`·`webhookSecret`을 생략하면
+			* 현재 세트의 값을 이어받고 `webhookSecret: null`은 삭제다. 저장하면 그 세트의 `lastVerification`이 초기화된다.
+			*
+			* 에러: 400 `PAYMENT_PROVIDER_INCOMPLETE`(시크릿 키 없음) · 400 `INVALID_CREDENTIALS`(형식·환경 불일치) ·
+			* 409 `PAYMENT_PROVIDER_VERIFICATION_FAILED`(라이브 사용 중인 PG의 LIVE 세트 가맹점을 바꾸려는데 저장 전 연결 테스트 실패.
+			* 저장되지 않는다. 같은 가맹점의 비밀 값 교체는 검사하지 않는다)
+			*/
+			upsertTossPayments: (body) => storeHttp.request("PUT", "/store/payment-providers/tosspayments", paymentProviderSchema, { body: upsertTossPaymentsProviderRequestSchema.parse(body) }),
+			/**
+			* `PUT /v1/store/payment-providers/portone` — 자격 증명 세트 저장. 규칙·에러는 `upsertTossPayments`와 같다
+			* (가맹점 식별자는 `storeId`, 비밀 필드는 `apiSecret`·`webhookSecret`). 400 `INVALID_CREDENTIALS`에는 채널 키 중복이 포함된다.
+			*/
+			upsertPortOne: (body) => storeHttp.request("PUT", "/store/payment-providers/portone", paymentProviderSchema, { body: upsertPortOneProviderRequestSchema.parse(body) }),
+			/**
+			* `PATCH /v1/store/payment-providers/{provider}` — 사용 여부(`enabled`)·샌드박스 스위치(`sandboxMode`) 변경.
+			* 하나 이상 보내야 한다(아니면 요청 전에 ZodError). 검증을 모두 통과해야 한 번에 적용된다(부분 적용 없음).
+			* 끈 PG로 승인된 결제의 환불은 계속 그 PG로 간다.
+			*
+			* 에러
+			* - 404 `PAYMENT_PROVIDER_NOT_FOUND`: 연결되지 않은 PG
+			* - 409 `PAYMENT_PROVIDER_INCOMPLETE`: 켜려는데 활성 환경(샌드박스면 TEST, 아니면 LIVE) 세트가 없거나 불완전
+			* - 409 `LIVE_GATE_NOT_MET`: `sandboxMode: false`(라이브 전환)인데 개방 조건 미충족. `ApiError.details`가
+			*   `{ conditions: LiveGateCondition[] }`(조건별 `met`)이다. `liveGateErrorDetailsSchema`로 파싱한다
+			* - 409 `LIVE_PAYMENTS_DISABLED`: 플랫폼 실결제 스위치만 미충족. `details`는 위와 같다
+			*
+			* `sandboxMode: true`는 항상 허용되고 즉시 실결제가 멈춘다.
+			*/
+			updateProvider: updatePaymentProvider,
+			/**
+			* 샌드박스 스위치만 바꾼다 — `updateProvider(provider, { sandboxMode })`와 같다.
+			* `false`(라이브 전환)는 409 `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`(둘 다 `ApiError.details.conditions`)가 날 수 있다.
+			*/
+			setSandboxMode: (provider, sandboxMode) => updatePaymentProvider(provider, { sandboxMode }),
+			/**
+			* `DELETE /v1/store/payment-providers/{provider}` (204) — 연결 해제. 결제 이력과 무관하게 허용된다.
+			* 모든 세트는 보관되고 PG 설정에서 사라진다. 이미 받은 결제의 취소·환불·대사는 보관된 자격 증명으로 계속 처리된다.
+			* 404 `PAYMENT_PROVIDER_NOT_FOUND`.
+			*/
+			disconnect: (provider) => storeHttp.requestVoid("DELETE", path`/store/payment-providers/${pgProviderSchema.parse(provider)}`),
+			/**
+			* `DELETE /v1/store/payment-providers/{provider}/credentials/{TEST|LIVE}` (200) — 활성 환경이 아닌 세트 하나를 보관 처리하고
+			* 갱신된 `PaymentProvider`를 돌려준다. 보관된 세트는 그 세트로 받은 결제의 환불에 계속 쓰인다.
+			*
+			* 에러: 404 `PAYMENT_PROVIDER_NOT_FOUND`(미연결 PG) · 404 `PAYMENT_CREDENTIAL_NOT_FOUND`(등록되지 않은 세트) ·
+			* 409 `PAYMENT_CREDENTIAL_ACTIVE`(지금 결제에 쓰는 세트. 먼저 `setSandboxMode`로 스위치를 바꾼다)
+			*/
+			removeCredentialSet: (provider, environment) => storeHttp.request("DELETE", path`/store/payment-providers/${pgProviderSchema.parse(provider)}/credentials/${pgEnvironmentSchema.parse(environment)}`, paymentProviderSchema),
+			/**
+			* `POST /v1/store/payment-providers/{provider}/verify` — 저장된 세트로 연결 테스트하고 결과를 그 세트에 저장한다.
+			* `environment`를 생략하면 활성 환경 세트를 테스트한다. 실패해도 200이고 `result: "FAILED"`와 `message`에 사유가 온다.
+			* 라이브 개방 조건 `TEST_CONNECTION`·`LIVE_CONNECTION`은 이 결과로 판정한다. 404 `PAYMENT_PROVIDER_NOT_FOUND`.
+			*/
+			verify: (provider, body) => storeHttp.request("POST", path`/store/payment-providers/${pgProviderSchema.parse(provider)}/verify`, paymentProviderVerificationSchema, { body: verifyPaymentProviderRequestSchema.parse(body ?? {}) })
+		},
+		webhooks: {
+			list: () => storeHttp.request("GET", "/webhooks", z.array(webhookSchema)),
+			/** 서명 시크릿 평문은 이 응답에서만 노출된다 */
+			create: (body) => storeHttp.request("POST", "/webhooks", webhookCreatedSchema, { body: webhookRequestSchema.parse(body) }),
+			get: (webhookId) => storeHttp.request("GET", path`/webhooks/${webhookId}`, webhookSchema),
+			/** SUSPENDED 구독은 수정하면 ACTIVE로 돌아간다. 수정된 구독을 돌려준다 */
+			update: (webhookId, body) => storeHttp.request("PUT", path`/webhooks/${webhookId}`, webhookSchema, { body: webhookRequestSchema.parse(body) }),
+			remove: (webhookId) => storeHttp.requestVoid("DELETE", path`/webhooks/${webhookId}`),
+			rotateSecret: (webhookId) => storeHttp.request("POST", path`/webhooks/${webhookId}/rotate-secret`, webhookSecretRotatedSchema),
+			/** SUSPENDED 구독을 ACTIVE로 재개하고 연속 실패 기록을 초기화한다. 이미 ACTIVE면 그대로 돌려준다(멱등) */
+			resume: (webhookId) => storeHttp.request("POST", path`/webhooks/${webhookId}/resume`, webhookSchema),
+			/** 전송 기록 (최신 적재순, 기본 50건·최대 100건, 보관 30일) */
+			listDeliveries: (webhookId, params) => storeHttp.request("GET", path`/webhooks/${webhookId}/deliveries`, z.array(webhookDeliverySchema), { query: params }),
+			/**
+			* FAILED 전송 기록 한 건을 같은 eventId로 다시 보낸다(202). 새로 적재된 기록을 돌려주며
+			* `redeliveryOf`가 원본 deliveryId다. 원본이 FAILED가 아니면 409 `DELIVERY_NOT_FAILED`,
+			* 원본이 이미 재전송됐으면 409 `DELIVERY_ALREADY_REDELIVERED`(원본당 1회, 원본의 `redeliveredAs` 참고),
+			* 구독이 SUSPENDED면 409 `WEBHOOK_SUSPENDED`.
+			*/
+			redeliver: (webhookId, deliveryId) => storeHttp.request("POST", path`/webhooks/${webhookId}/deliveries/${deliveryId}/redeliver`, webhookDeliverySchema),
+			/**
+			* 최근 72시간의 FAILED 중 아직 재전송되지 않은 건 전체(최대 500건)를 다시 보낸다(202).
+			* 구독이 SUSPENDED면 409 `WEBHOOK_SUSPENDED` — 먼저 `resume`한다.
+			*/
+			redeliverFailed: (webhookId) => storeHttp.request("POST", path`/webhooks/${webhookId}/deliveries/redeliver-failed`, webhookRedeliverFailedResultSchema),
+			/**
+			* 지정한 이벤트 타입의 샘플 페이로드(이벤트 id `evt_test_…`)를 실제로 보내고 수신 서버 응답을
+			* 동기로 돌려준다. 재시도·정지 판정·전송 기록이 없다.
+			*/
+			sendTest: (webhookId, body) => storeHttp.request("POST", path`/webhooks/${webhookId}/test`, webhookTestResultSchema, { body: webhookTestRequestSchema.parse(body) })
+		},
+		/** API 로그 (보관 7일, 콘솔 OWNER/ADMIN) */
+		apiLogs: {
+			/** 최신순 커서 페이지네이션. 다음 페이지는 응답의 `nextCursor`를 `cursor`로 넘긴다 */
+			list: (params) => storeHttp.request("GET", "/api-logs", apiLogPageSchema, { query: params && {
+				...params,
+				principalType: Array.isArray(params.principalType) ? params.principalType.join(",") || void 0 : params.principalType
+			} }),
+			/** 최근 24시간 요청 수·에러 수 */
+			summary: () => storeHttp.request("GET", "/api-logs/summary", apiLogSummarySchema)
+		},
+		reviews: {
+			list: (params) => storeHttp.request("GET", "/reviews", pageSchema(reviewSchema), { query: params }),
+			get: (reviewId) => storeHttp.request("GET", path`/reviews/${reviewId}`, reviewSchema),
+			createReply: (reviewId, content) => storeHttp.requestVoid("POST", path`/reviews/${reviewId}/reply`, { body: { content } }),
+			updateReply: (reviewId, content) => storeHttp.requestVoid("PUT", path`/reviews/${reviewId}/reply`, { body: { content } }),
+			deleteReply: (reviewId) => storeHttp.requestVoid("DELETE", path`/reviews/${reviewId}/reply`)
+		},
+		sellerAddresses: {
+			list: (type) => storeHttp.request("GET", "/seller-addresses", z.array(sellerAddressSchema), { query: { type } }),
+			create: (body) => storeHttp.requestVoid("POST", "/seller-addresses", { body: sellerAddressRequestSchema.parse(body) }),
+			update: (addressId, body) => storeHttp.requestVoid("PUT", path`/seller-addresses/${addressId}`, { body: sellerAddressRequestSchema.parse(body) }),
+			remove: (addressId) => storeHttp.requestVoid("DELETE", path`/seller-addresses/${addressId}`),
+			setDefault: (addressId) => storeHttp.requestVoid("POST", path`/seller-addresses/${addressId}/default`)
+		},
+		store: {
+			get: () => storeHttp.request("GET", "/store", storeSchema),
+			listMembers: () => storeHttp.request("GET", "/store/members", z.array(storeMemberSchema)),
+			listInvitations: () => storeHttp.request("GET", "/store/invitations", z.array(invitationSchema))
+		}
+	};
+}
+//#endregion
+//#region src/oauth.ts
+/**
+* OAuth 2.1 브라우저 플로우 헬퍼 (authorization_code + PKCE).
+* Web Crypto만 사용 — 브라우저/Node 모두에서 동작하며 **시크릿을 다루지 않는다**.
+*/
+/** RFC 6749 §5.1 토큰 응답 (+ RFC 8693 확장 멤버 허용) */
+const oauthTokenResponseSchema = z.object({
+	access_token: z.string(),
+	token_type: z.literal("Bearer"),
+	expires_in: z.number().int(),
+	scope: z.string().optional(),
+	refresh_token: z.string().optional()
+}).loose();
+/** PKCE 페어 생성 — verifier(43~128자) + S256 challenge */
+async function createPkcePair() {
+	const random = /* @__PURE__ */ new Uint8Array(48);
+	crypto.getRandomValues(random);
+	const verifier = base64UrlFromBytes(random);
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+	return {
+		verifier,
+		challenge: base64UrlFromBytes(new Uint8Array(digest))
+	};
+}
+/** authorize 엔드포인트 URL 구성 — 브라우저는 이 URL로 이동(top-level navigation) */
+function buildAuthorizeUrl(options) {
+	const url = new URL(`${options.baseUrl}/oauth2/authorize`);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("client_id", options.clientId);
+	url.searchParams.set("redirect_uri", options.redirectUri);
+	url.searchParams.set("state", options.state);
+	url.searchParams.set("code_challenge", options.codeChallenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	if (options.scope) url.searchParams.set("scope", options.scope);
+	return url.toString();
+}
+async function tokenRequest(baseUrl, form, fetchFn = globalThis.fetch) {
+	const response = await fetchFn(`${baseUrl}/oauth2/token`, {
+		method: "POST",
+		headers: { "content-type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams(form).toString()
+	});
+	const json = await response.json().catch(() => null);
+	if (!response.ok) {
+		const body = json;
+		throw new Error(body?.error_description ?? body?.error ?? `HTTP ${response.status}`);
+	}
+	return oauthTokenResponseSchema.parse(unwrapData(json));
+}
+/** 콜백에서 받은 code를 userToken으로 교환 (PKCE verifier 동반) */
+async function exchangeAuthorizationCode(options) {
+	return tokenRequest(options.baseUrl, {
+		grant_type: "authorization_code",
+		code: options.code,
+		redirect_uri: options.redirectUri,
+		client_id: options.clientId,
+		code_verifier: options.codeVerifier
+	}, options.fetch);
+}
+/** refresh grant (rotation — 응답의 새 refresh_token으로 반드시 교체 저장할 것) */
+async function refreshUserToken(options) {
+	return tokenRequest(options.baseUrl, {
+		grant_type: "refresh_token",
+		refresh_token: options.refreshToken,
+		client_id: options.clientId
+	}, options.fetch);
+}
+/** userToken → storeToken 교환 (RFC 8693 token-exchange grant) */
+async function exchangeStoreTokenViaOAuth(options) {
+	return tokenRequest(options.baseUrl, {
+		grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+		subject_token: options.userToken,
+		subject_token_type: "urn:ietf:params:oauth:token-type:access_token",
+		audience: options.storeId,
+		client_id: options.clientId
+	}, options.fetch);
+}
+//#endregion
+//#region src/schemas/scope.ts
+/**
+* 스토어 스코프 카탈로그 (auth-spec §7) — 형식 `{리소스}:{r|rw}`, rw는 r을 함의한다.
+*
+* 관리 API가 요구하는 스코프와 역할별 자동 부여 스코프의 **단일 원천**이다.
+* 서버(apps/api)가 이 상수를 그대로 가져다 역할→스코프를 산출하므로, 콘솔 권한 매트릭스와
+* 서버 인가가 갈라지지 않는다.
+*/
+const scopeAccessSchema = z.enum(["r", "rw"]).describe("접근 수준. `r`=읽기, `rw`=읽기+쓰기(r을 함의)");
+/** 리소스별로 부여 가능한 접근 수준. settlement는 쓰기 API가 없어 `r`만 존재한다 */
+const STORE_SCOPE_RESOURCES = {
+	product: ["r", "rw"],
+	category: ["r", "rw"],
+	order: ["r", "rw"],
+	claim: ["r", "rw"],
+	inquiry: ["r", "rw"],
+	review: ["r", "rw"],
+	settlement: ["r"],
+	webhook: ["r", "rw"],
+	store: ["r", "rw"],
+	member: ["r", "rw"]
+};
+const storeScopeResourceSchema = z.enum(Object.keys(STORE_SCOPE_RESOURCES)).describe("스코프 리소스");
+/** 카탈로그상 존재하는 스코프 문자열인가 (예: `settlement:rw`는 false) */
+function isStoreScope(scope) {
+	const [resource, access, ...rest] = scope.split(":");
+	if (rest.length > 0 || !resource || !access) return false;
+	return STORE_SCOPE_RESOURCES[resource]?.includes(access) ?? false;
+}
+/**
+* 역할별 자동 부여 스코프 (auth-spec §7).
+* storeToken(사람)의 스코프는 이 표로 결정된다. PAT·M2M 클라이언트에는 역할이 없고
+* 발급 시 지정한 스코프만 갖는다(발급자 보유 스코프 이내).
+*/
+const STORE_ROLE_SCOPES = {
+	OWNER: [
+		"product:rw",
+		"category:rw",
+		"order:rw",
+		"claim:rw",
+		"inquiry:rw",
+		"review:rw",
+		"settlement:r",
+		"webhook:rw",
+		"store:rw",
+		"member:rw"
+	],
+	ADMIN: [
+		"product:rw",
+		"category:rw",
+		"order:rw",
+		"claim:rw",
+		"inquiry:rw",
+		"review:rw",
+		"webhook:rw",
+		"store:rw",
+		"member:rw"
+	],
+	STAFF: [
+		"product:rw",
+		"category:rw",
+		"order:rw",
+		"claim:rw",
+		"inquiry:rw",
+		"review:rw"
+	]
+};
+//#endregion
+//#region src/schemas/webhook-event.ts
+const envelopeFields = {
+	id: z.string().describe("이벤트 ID (`evt_…`, 테스트 전송은 `evt_test_…`). 중복 제거 키"),
+	createdAt: z.string().describe("이벤트 발생 일시 (ISO 8601)"),
+	storeId: z.string().describe("이벤트가 발생한 스토어 ID")
+};
+const orderWebhookEventDataSchema = z.object({
+	orderId: z.string().describe("주문 ID"),
+	status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
+	testPayment: z.boolean().optional().default(false).describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다. 이 필드가 없는 이전 이벤트는 false로 읽는다")
+});
+const claimWebhookEventDataSchema = z.object({
+	claimId: z.string().describe("클레임 ID"),
+	orderId: z.string().describe("주문 ID"),
+	orderItemId: z.string().describe("클레임 대상 주문 상품 ID"),
+	claimType: claimTypeSchema.describe("클레임 유형"),
+	status: claimStatusSchema.describe("이벤트 발생 시점의 클레임 상태"),
+	testPayment: z.boolean().optional().default(false).describe("테스트 결제(샌드박스 결제) 주문의 클레임인가. 이 필드가 없는 이전 이벤트는 false로 읽는다")
+});
+const inquiryWebhookEventDataSchema = z.object({
+	inquiryId: z.string().describe("상품 문의 ID"),
+	productId: z.string().describe("상품 ID")
+});
+const reviewWebhookEventDataSchema = z.object({
+	reviewId: z.string().describe("리뷰 ID"),
+	productId: z.string().describe("상품 ID"),
+	rating: z.number().int().min(1).max(5).describe("별점 (1~5)")
+});
+const productOutOfStockWebhookEventDataSchema = z.object({
+	productId: z.string().describe("상품 ID"),
+	variantId: z.string().describe("재고가 0이 된 판매 단위(variant) ID. 주문 상품의 `optionId`와 같은 값 공간이다")
+});
+const orderWebhookEventSchema = z.object({
+	...envelopeFields,
+	type: z.enum([
+		"ORDER.PAID",
+		"ORDER.CONFIRMED",
+		"ORDER.DISPATCHED",
+		"ORDER.DELIVERED",
+		"ORDER.PURCHASE_DECIDED",
+		"ORDER.ADDRESS_CHANGE_REQUESTED"
+	]),
+	data: orderWebhookEventDataSchema
+});
+const claimWebhookEventSchema = z.object({
+	...envelopeFields,
+	type: z.enum([
+		"CLAIM.CANCEL_REQUESTED",
+		"CLAIM.RETURN_REQUESTED",
+		"CLAIM.EXCHANGE_REQUESTED",
+		"CLAIM.COMPLETED"
+	]),
+	data: claimWebhookEventDataSchema
+});
+const inquiryWebhookEventSchema = z.object({
+	...envelopeFields,
+	type: z.literal("INQUIRY.CREATED"),
+	data: inquiryWebhookEventDataSchema
+});
+const reviewWebhookEventSchema = z.object({
+	...envelopeFields,
+	type: z.literal("REVIEW.CREATED"),
+	data: reviewWebhookEventDataSchema
+});
+const productOutOfStockWebhookEventSchema = z.object({
+	...envelopeFields,
+	type: z.literal("PRODUCT.OUT_OF_STOCK"),
+	data: productOutOfStockWebhookEventDataSchema
+});
+/** 웹훅 요청 본문. `type`으로 판별하며 `data` 형태가 타입별로 다르다 */
+const webhookEventSchema = z.discriminatedUnion("type", [
+	orderWebhookEventSchema,
+	claimWebhookEventSchema,
+	inquiryWebhookEventSchema,
+	reviewWebhookEventSchema,
+	productOutOfStockWebhookEventSchema
+]).describe("웹훅 요청 본문 (얇은 이벤트). 개인정보를 싣지 않으며 `data`의 id로 관리 API를 조회한다");
+//#endregion
+//#region src/session.ts
+/**
+* 세션 키 상수 — SDK가 소유한다. 값은 apps/store의 기존 쿠키 이름(SESSION_COOKIE/REFRESH_COOKIE)과
+* 동일하게 맞춰, 앱 어댑터·SSR 라우트 가드가 같은 원천을 읽도록 패리티를 보장한다.
+*/
+const STORE_SESSION_KEYS = {
+	session: "sayren.store.session",
+	refresh: "sayren.store.refresh",
+	/** authorize() → handleCallback() 간 1회용 PKCE 블롭({ verifier, state, redirectUri }) 저장 키 */
+	pkce: "sayren.store.pkce"
+};
+/** Web Locks 이름 — 탭 간 refresh 회전 직렬화용 */
+const REFRESH_LOCK = STORE_SESSION_KEYS.refresh;
+function createStoreSession(options) {
+	const { baseUrl, clientId, storage } = options;
+	const fetchFn = options.fetch ?? globalThis.fetch;
+	const listeners = /* @__PURE__ */ new Set();
+	function notify() {
+		for (const listener of listeners) listener();
+	}
+	function getToken() {
+		return storage.get(STORE_SESSION_KEYS.session);
+	}
+	function setTokens(tokens) {
+		storage.set(STORE_SESSION_KEYS.session, tokens.access_token);
+		if (tokens.refresh_token) storage.set(STORE_SESSION_KEYS.refresh, tokens.refresh_token);
+		notify();
+	}
+	function clear() {
+		storage.remove(STORE_SESSION_KEYS.session);
+		storage.remove(STORE_SESSION_KEYS.refresh);
+		notify();
+	}
+	let refreshInFlight = null;
+	function refresh() {
+		if (!refreshInFlight) refreshInFlight = doRefresh().finally(() => {
+			refreshInFlight = null;
+		});
+		return refreshInFlight;
+	}
+	async function doRefresh() {
+		const before = getToken();
+		const locks = typeof navigator !== "undefined" ? navigator.locks : void 0;
+		return locks ? locks.request(REFRESH_LOCK, () => rotate(before)) : rotate(before);
+	}
+	async function rotate(before) {
+		if (getToken() !== before) return true;
+		const refreshToken = storage.get(STORE_SESSION_KEYS.refresh);
+		if (!refreshToken) return false;
+		try {
+			const tokens = await refreshUserToken({
+				baseUrl,
+				clientId,
+				refreshToken,
+				fetch: fetchFn
+			});
+			setTokens({
+				access_token: tokens.access_token,
+				refresh_token: tokens.refresh_token
+			});
+			return true;
+		} catch {
+			clear();
+			return false;
+		}
+	}
+	function subscribe(cb) {
+		listeners.add(cb);
+		return () => {
+			listeners.delete(cb);
+		};
+	}
+	/** crypto.randomUUID가 있으면 그걸, 없으면 무작위 바이트를 base64url로 인코딩해 state를 만든다 */
+	function randomState() {
+		if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+		const bytes = /* @__PURE__ */ new Uint8Array(16);
+		crypto.getRandomValues(bytes);
+		return base64UrlFromBytes(bytes);
+	}
+	async function authorize(authorizeOptions) {
+		const { verifier, challenge } = await createPkcePair();
+		const state = randomState();
+		const blob = {
+			verifier,
+			state,
+			redirectUri: authorizeOptions.redirectUri
+		};
+		storage.set(STORE_SESSION_KEYS.pkce, JSON.stringify(blob));
+		const url = new URL(buildAuthorizeUrl({
+			baseUrl,
+			clientId,
+			redirectUri: authorizeOptions.redirectUri,
+			state,
+			codeChallenge: challenge,
+			scope: authorizeOptions.scope
+		}));
+		if (authorizeOptions.screen === "signup") url.pathname = url.pathname.replace(/\/oauth2\/authorize$/, "/oauth2/signup");
+		const finalUrl = url.toString();
+		if (typeof window !== "undefined") {
+			window.location.assign(finalUrl);
+			return;
+		}
+		return finalUrl;
+	}
+	async function handleCallback(code, state) {
+		const raw = storage.get(STORE_SESSION_KEYS.pkce);
+		storage.remove(STORE_SESSION_KEYS.pkce);
+		if (!raw) throw new Error("로그인 세션이 만료되었습니다. 다시 시도해주세요");
+		const saved = JSON.parse(raw);
+		if (saved.state !== state) throw new Error("state가 일치하지 않습니다. 다시 시도해주세요");
+		const tokens = await exchangeAuthorizationCode({
+			baseUrl,
+			clientId,
+			redirectUri: saved.redirectUri,
+			code,
+			codeVerifier: saved.verifier,
+			fetch: fetchFn
+		});
+		setTokens({
+			access_token: tokens.access_token,
+			refresh_token: tokens.refresh_token
+		});
+	}
+	async function userinfo() {
+		const token = getToken();
+		if (!token) return null;
+		const response = await fetchFn(`${baseUrl}/me`, { headers: { authorization: `Bearer ${token}` } });
+		const json = await response.json().catch(() => null);
+		if (!response.ok) throw toApiError(response.status, json);
+		return myAccountSchema.parse(unwrapData(json));
+	}
+	return {
+		getToken,
+		setTokens,
+		refresh,
+		clear,
+		subscribe,
+		authorize,
+		handleCallback,
+		userinfo,
+		get accessToken() {
+			return getToken();
+		},
+		get refreshToken() {
+			return storage.get(STORE_SESSION_KEYS.refresh);
+		}
+	};
+}
+//#endregion
+export { ApiError, MAX_OPTION_GROUPS, MAX_VALUES_PER_GROUP, MAX_VARIANTS, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, RESERVED_STORE_CODES, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressTypeSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approveClaimResultSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, carrierSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteStrategySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimReasonSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, createPkcePair, createStoreClient, createStoreSession, customerInquiryCategorySchema, deliveryInfoSchema, deliveryMethodSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, effectivePaymentRoutingModeSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationSchema, isReservedStoreCode, isStoreScope, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentRoutingModeSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, refreshUserToken, rejectClaimRequestSchema, reviewSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, scopeAccessSchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailSchema, settlementStatusSchema, settlementSummarySchema, shippingAddressSchema, storeCodeSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema };