@sayren/store-sdk 0.23.0 → 0.28.0

package/src/oauth.ts

@@ -4,10 +4,11 @@ import { unwrapData } from "./http";
 
 /**
  * OAuth 2.1 브라우저 플로우 헬퍼 (authorization_code + PKCE).
+ * 발급자는 Sayren 계정(accounts)이다 — 엔드포인트 주소는 호출부가 준다.
  * Web Crypto만 사용 — 브라우저/Node 모두에서 동작하며 **시크릿을 다루지 않는다**.
  */
 
-/** RFC 6749 §5.1 토큰 응답 (+ RFC 8693 확장 멤버 허용) */
+/** RFC 6749 §5.1 토큰 응답 */
 export const oauthTokenResponseSchema = z
   .object({
     access_token: z.string(),
@@ -29,19 +30,23 @@ export async function createPkcePair(): Promise<{ verifier: string; challenge: s
 }
 
 export interface AuthorizeUrlOptions {
-  /** 예: https://api.sayren.app/v1 (베이스 URL — /oauth2/authorize가 덧붙는다) */
-  baseUrl: string;
+  /** authorize 엔드포인트 전체 주소(예: `https://accounts.sayren.app/api/auth/oauth2/authorize`) */
+  authorizeUrl: string;
   clientId: string;
   redirectUri: string;
   state: string;
   codeChallenge: string;
-  /** 생략 시 서버 기본(stores:read). refresh가 필요하면 offline_access 포함 */
+  /** 생략 시 발급자 기본. refresh가 필요하면 offline_access 포함 */
   scope?: string;
+  /** RFC 8707 리소스 지시자 — 주면 JWT access token(`aud` = 리소스)을 받는다 */
+  resource?: string;
+  /** OIDC `prompt` — `login`(재인증)·`create`(가입)·`consent`(동의 다시 받기) */
+  prompt?: "login" | "create" | "consent";
 }
 
 /** authorize 엔드포인트 URL 구성 — 브라우저는 이 URL로 이동(top-level navigation) */
 export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
-  const url = new URL(`${options.baseUrl}/oauth2/authorize`);
+  const url = new URL(options.authorizeUrl);
   url.searchParams.set("response_type", "code");
   url.searchParams.set("client_id", options.clientId);
   url.searchParams.set("redirect_uri", options.redirectUri);
@@ -49,15 +54,18 @@ export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
   url.searchParams.set("code_challenge", options.codeChallenge);
   url.searchParams.set("code_challenge_method", "S256");
   if (options.scope) url.searchParams.set("scope", options.scope);
+  if (options.resource) url.searchParams.set("resource", options.resource);
+  if (options.prompt) url.searchParams.set("prompt", options.prompt);
   return url.toString();
 }
 
 async function tokenRequest(
-  baseUrl: string,
+  endpoint: string,
   form: Record<string, string>,
   fetchFn: typeof globalThis.fetch = globalThis.fetch,
 ): Promise<OAuthTokenResponse> {
-  const response = await fetchFn(`${baseUrl}/oauth2/token`, {
+  // 자격 증명(쿠키)을 싣지 않는다 — public 클라이언트 + PKCE·refresh로만 인증한다(다른 origin 발급자도 같다)
+  const response = await fetchFn(endpoint, {
     method: "POST",
     headers: { "content-type": "application/x-www-form-urlencoded" },
     body: new URLSearchParams(form).toString(),
@@ -70,23 +78,27 @@ async function tokenRequest(
   return oauthTokenResponseSchema.parse(unwrapData(json));
 }
 
-/** 콜백에서 받은 code를 userToken으로 교환 (PKCE verifier 동반) */
+/** 콜백에서 받은 code를 액세스 토큰으로 교환 (PKCE verifier 동반) */
 export async function exchangeAuthorizationCode(options: {
-  baseUrl: string;
+  /** 토큰 엔드포인트 전체 주소 */
+  tokenUrl: string;
   clientId: string;
   redirectUri: string;
   code: string;
   codeVerifier: string;
+  /** RFC 8707 리소스 지시자 */
+  resource?: string;
   fetch?: typeof globalThis.fetch;
 }): Promise<OAuthTokenResponse> {
   return tokenRequest(
-    options.baseUrl,
+    options.tokenUrl,
     {
       grant_type: "authorization_code",
       code: options.code,
       redirect_uri: options.redirectUri,
       client_id: options.clientId,
       code_verifier: options.codeVerifier,
+      ...(options.resource ? { resource: options.resource } : {}),
     },
     options.fetch,
   );
@@ -94,38 +106,21 @@ export async function exchangeAuthorizationCode(options: {
 
 /** refresh grant (rotation — 응답의 새 refresh_token으로 반드시 교체 저장할 것) */
 export async function refreshUserToken(options: {
-  baseUrl: string;
+  /** 토큰 엔드포인트 전체 주소 */
+  tokenUrl: string;
   clientId: string;
   refreshToken: string;
+  /** RFC 8707 리소스 지시자 */
+  resource?: string;
   fetch?: typeof globalThis.fetch;
 }): Promise<OAuthTokenResponse> {
   return tokenRequest(
-    options.baseUrl,
+    options.tokenUrl,
     {
       grant_type: "refresh_token",
       refresh_token: options.refreshToken,
       client_id: options.clientId,
-    },
-    options.fetch,
-  );
-}
-
-/** userToken → storeToken 교환 (RFC 8693 token-exchange grant) */
-export async function exchangeStoreTokenViaOAuth(options: {
-  baseUrl: string;
-  clientId: string;
-  userToken: string;
-  storeId: string;
-  fetch?: typeof globalThis.fetch;
-}): Promise<OAuthTokenResponse & { storeId?: string; role?: string }> {
-  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.resource ? { resource: options.resource } : {}),
     },
     options.fetch,
   );

package/src/schemas/auth.ts

@@ -4,35 +4,6 @@ export const storeRoleSchema = z.enum(["OWNER", "ADMIN", "STAFF"]);
 
 export type StoreRole = z.infer<typeof storeRoleSchema>;
 
-export const userTokenResponseSchema = z.object({
-  access_token: z.string(),
-  token_type: z.literal("Bearer"),
-  expires_in: z.number().int(),
-  refresh_token: z.string().optional(),
-});
-
-export type UserTokenResponse = z.infer<typeof userTokenResponseSchema>;
-
-/** client_credentials 응답 (RFC 6749 §4.4.3) — storeToken 직발급, refresh 없음 */
-export const clientCredentialsTokenResponseSchema = z.object({
-  access_token: z.string(),
-  token_type: z.literal("Bearer"),
-  expires_in: z.number().int(),
-  scope: z.string(),
-});
-export type ClientCredentialsTokenResponse = z.infer<typeof clientCredentialsTokenResponseSchema>;
-
-export 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()),
-});
-
-export type StoreTokenResponse = z.infer<typeof storeTokenResponseSchema>;
-
 export const myStoreSchema = z.object({
   storeId: z.string(),
   storeName: z.string(),
@@ -52,38 +23,3 @@ export const myAccountSchema = z.object({
 });
 
 export type MyAccount = z.infer<typeof myAccountSchema>;
-
-/** API 토큰(PAT) — 목록/조회 뷰 (평문·해시 미포함) */
-export 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(),
-  agent: z
-    .boolean()
-    .default(false)
-    .describe(
-      "AI 에이전트(MCP)용 토큰인가. true면 이 토큰의 쓰기는 행위자 `AGENT`로 기록되고 에이전트 쓰기 정책(승인 필요·거부)을 따른다",
-    ),
-});
-export type ApiToken = z.infer<typeof apiTokenSchema>;
-
-/** 생성 응답 — 평문 토큰은 이 응답에서 단 한 번만 노출된다 */
-export const apiTokenCreatedSchema = apiTokenSchema.extend({ token: z.string() });
-export type ApiTokenCreated = z.infer<typeof apiTokenCreatedSchema>;
-
-export 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(),
-  /** AI 에이전트(MCP)용 토큰. 생략 = false. 발급 뒤에는 바꿀 수 없다 */
-  agent: z.boolean().optional(),
-});
-export type ApiTokenCreateRequest = z.infer<typeof apiTokenCreateRequestSchema>;

package/src/schemas/customer-delegation.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+/**
+ * 구매자 위임 REST(`POST /v1/customers/delegations`, #71) — 계정 토큰(또는 관리 API 토큰) + `X-Store-Id`로 부른다(`customer:rw`).
+ * 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰(30분, refresh 없음)으로 바꾼다. 옛 token-exchange
+ * (`member-uid`·`member-ref`)를 대신한다. 에이전트 요청은 거부된다(`x-agent-policy` DENIED).
+ */
+
+const uidPattern = /^[A-Za-z0-9._:@|-]{1,128}$/;
+
+export const customerDelegationRequestSchema = z
+  .object({
+    uid: z
+      .string()
+      .regex(uidPattern)
+      .optional()
+      .describe(
+        "셀러 자체 인증의 사용자 id(1~128자, 영문·숫자·`._:@|-`). 처음 보는 id면 구매자를 만든다",
+      ),
+    email: z
+      .email()
+      .max(254)
+      .optional()
+      .describe("uid가 없으면 이메일로 지목한다. uid와 함께 주면 처음 만들 때의 이메일이다"),
+    name: z.string().max(50).optional().describe("처음 만들 때의 이름"),
+    authenticatedAt: z.iso
+      .datetime({ offset: true })
+      .optional()
+      .describe(
+        "사용자가 셀러 서비스에서 실제로 로그인한 시각(uid 위임만). 주면 구매자 토큰의 인증 시각이 된다",
+      ),
+  })
+  .refine((value) => Boolean(value.uid || value.email), {
+    message: "uid 또는 email이 필요합니다",
+    path: ["uid"],
+  })
+  .describe("구매자 위임 요청");
+export type CustomerDelegationRequest = z.infer<typeof customerDelegationRequestSchema>;
+
+export const customerDelegationSchema = z
+  .object({
+    accessToken: z.string().describe("구매자 액세스 토큰(스토어프론트 API Bearer)"),
+    tokenType: z.literal("Bearer"),
+    expiresIn: z.number().int().describe("수명(초)"),
+    memberId: z.string(),
+  })
+  .describe("구매자 위임 결과");
+export type CustomerDelegation = z.infer<typeof customerDelegationSchema>;

package/src/schemas/product.ts

@@ -35,6 +35,13 @@ export const productSummarySchema = z.object({
       "상품 이행의 유형. 유형별 속성은 단건 조회(`GET /v1/products/{productId}`)의 `fulfillment`에 있다",
     ),
   updatedAt: z.string(),
+  sample: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "스토어를 만들 때 넣은 샘플 상품인가(이슈 #70). 콘솔이 「샘플」 배지를 단다. 스토어프론트에는 싣지 않는다. 서버는 항상 싣는다",
+    ),
 });
 
 export type ProductSummary = z.infer<typeof productSummarySchema>;

package/src/schemas/scope.ts

@@ -49,8 +49,7 @@ export function isStoreScope(scope: string): boolean {
 
 /**
  * 역할별 자동 부여 스코프 (auth-spec §7).
- * storeToken(사람)의 스코프는 이 표로 결정된다. PAT·M2M 클라이언트에는 역할이 없고
- * 발급 시 지정한 스코프만 갖는다(발급자 보유 스코프 이내).
+ * 계정 토큰으로 스토어를 호출할 때의 스코프는 그 스토어에서의 역할로 이 표에서 결정된다.
  */
 export const STORE_ROLE_SCOPES = {
   OWNER: [

package/src/schemas/store.ts

@@ -270,7 +270,7 @@ export type StoreMember = z.infer<typeof storeMemberSchema>;
 
 /**
  * 초대 메일 발송 결과 — `SENDING`은 발송 요청 중(결과를 아직 적지 못함), `NOT_CONFIGURED`는 메일 발송이 설정되지 않아
- * 보내지 않은 것이다. 발송 실패는 초대를 무효로 만들지 않는다 — 재발송으로 다시 보낸다
+ * 보내지 않은 것이다. 스토어의 월 메일 한도(요금제)를 다 써서 보내지 않았으면 `FAILED` + `deliveryErrorCode: MAIL_QUOTA_EXCEEDED`다. 발송 실패는 초대를 무효로 만들지 않는다 — 재발송으로 다시 보낸다
  */
 export const invitationDeliveryStatusSchema = z.enum([
   "SENDING",

package/src/schemas/storefront-hosting.ts

@@ -24,6 +24,7 @@ import { RESERVED_STORE_CODES } from "./store";
  * - 409 `STORE_SUSPENDED` — 정지된 스토어에는 사이트를 만들 수 없다
  * - 409 `STOREFRONT_VERSION_NOT_READY` — 빌드가 끝나지 않았거나 실패한 버전은 발행할 수 없다
  * - 409 `STOREFRONT_NO_ROLLBACK_TARGET` — 되돌릴 이전 발행 버전이 없다
+ * - 409 `STOREFRONT_NOT_READY` — 공개 전환: 판매 중인 상품(샘플 제외)이 없다(이슈 #70). 상품을 등록한 뒤 공개한다
  * - 409 `TEMPLATE_CHANGE_NOT_SUPPORTED` — 템플릿 변경(`POST /v1/storefront/site/template`, 폐기)은 항상 이 오류다
  * - 400 `STOREFRONT_SLUG_CONFIRM_MISMATCH` — 호스팅 끄기 확인 입력이 현재 슬러그와 다르다
  * - 503 `STOREFRONT_PREVIEW_NOT_CONFIGURED` — 미리보기 서명 키가 설정되지 않았다
@@ -91,6 +92,16 @@ export const RESERVED_STOREFRONT_SLUGS: readonly string[] = [
  */
 export const STOREFRONT_EDIT_PREVIEW_SUFFIX = "-preview";
 
+/**
+ * 공식 쇼케이스 슬러그 접두사(이슈 #72) — `demo-{템플릿 id}`는 템플릿 미리보기용 쇼케이스 사이트 주소다. 쇼케이스로 지정된
+ * 스토어만 쓸 수 있다(서버가 스토어 용도로 판정한다). 공식 미리보기를 흉내 내는 주소를 막는다
+ */
+export const STOREFRONT_SHOWCASE_SLUG_PREFIX = "demo-";
+
+export function isShowcaseStorefrontSlug(slug: string): boolean {
+  return slug.toLowerCase().startsWith(STOREFRONT_SHOWCASE_SLUG_PREFIX);
+}
+
 export function isReservedStorefrontSlug(slug: string): boolean {
   const lower = slug.toLowerCase();
   return (
@@ -136,6 +147,23 @@ export const storefrontTemplateSchema = z.object({
   thumbnailUrl: z.string().nullable().describe("썸네일 이미지 주소. 없으면 null"),
   version: z.string().describe("현재 템플릿 버전. 새 사이트는 이 버전으로 만든다"),
   isDefault: z.boolean().describe("기본 템플릿인가 (스토어 생성 시 자동 생성에 쓴다)"),
+  tags: z
+    .array(z.string())
+    .default([])
+    .describe(
+      "템플릿 특징 태그 (예: `후기 강조`). 목록 카드에 보인다. 옛 서버 응답은 빈 배열로 읽는다",
+    ),
+  supportsCheckout: z
+    .boolean()
+    .default(true)
+    .describe(
+      "주문을 받는 템플릿인가. false는 가격·문의 중심의 카탈로그형이다. 옛 서버 응답은 true로 읽는다",
+    ),
+  previewUrl: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe("공식 쇼케이스 사이트 주소. 연결된 쇼케이스가 공개 중일 때만 싣고 그 밖에는 null"),
 });
 export type StorefrontTemplate = z.infer<typeof storefrontTemplateSchema>;
 

package/src/schemas/subscription.ts

@@ -0,0 +1,222 @@
+import { z } from "zod";
+
+/**
+ * 요금제·구독 — `GET /v1/store/subscription`(스코프 `store:r`). 구독 단위는 스토어다.
+ * 결제 수단·청구 금액은 싣지 않는다. 요금제 변경은 셀러 콘솔에서만 한다.
+ */
+
+/** 요금제 코드 — 이름(`plan.name`)이 바뀌어도 코드는 바뀌지 않는다. 값은 추가만 한다 */
+export const planCodeSchema = z
+  .enum(["BETA", "FREE", "BASIC", "PRO", "BUSINESS", "ENTERPRISE", "PREMIUM"])
+  .describe(
+    "요금제 코드. `FREE`=Free, `PRO`=Pro, `PREMIUM`=프리미엄, `ENTERPRISE`=엔터프라이즈, `BETA`=베타(운영 오픈 기간). `BASIC`·`BUSINESS`는 2026-09-30 이전 요금제(더 쓰지 않는다)",
+  );
+export type PlanCode = z.infer<typeof planCodeSchema>;
+
+/**
+ * 응답의 요금제 코드 — 아는 코드(`PlanCode`)거나 이 SDK가 모르는 새 코드(문자열)다. 요금제 코드는 추가될 수 있어 응답 파싱을 깨지 않게
+ * 넓게 받는다(옛 SDK는 새 코드를 모르면 파싱에 실패했다, #44 리뷰 M3). 요청에는 `planCodeSchema`를 쓴다
+ */
+export const responsePlanCodeSchema = z
+  .union([planCodeSchema, z.string()])
+  .describe(planCodeSchema.description ?? "요금제 코드");
+export type ResponsePlanCode = PlanCode | (string & {});
+
+export const subscriptionStatusSchema = z
+  .enum(["ACTIVE", "PAST_DUE", "CANCELED", "INCOMPLETE"])
+  .describe(
+    "구독 상태. `ACTIVE`=이용 중, `PAST_DUE`=결제 실패 후 유예 중, `CANCELED`=해지됨, `INCOMPLETE`=첫 결제 대기",
+  );
+export type SubscriptionStatus = z.infer<typeof subscriptionStatusSchema>;
+
+const limit = (description: string) =>
+  z.number().int().nullable().describe(`${description}. null이면 한도 없음`);
+
+export const subscriptionLimitsSchema = z.object({
+  liveOrdersMonthly: limit("더 쓰지 않는다 — 라이브 주문 수로 요금제를 나누지 않아 항상 null"),
+  seatsIncluded: limit("구성원 석 — 구성원은 모든 요금제에서 무료·무제한이라 null"),
+  aiActionsMonthly: limit("MCP(에이전트) 쓰기(AI 작업) 월 한도"),
+  aiReadsMonthly: limit("MCP(에이전트) 읽기 월 한도"),
+  customDomains: limit("내 도메인 수"),
+  webhooks: limit("웹훅 구독 수(0이면 쓸 수 없다)"),
+  socialProviders: limit("더 쓰지 않는다 — 소셜 로그인 공급자 수로 요금제를 나누지 않아 항상 null"),
+  emailsMonthly: limit("더 쓰지 않는다 — 메일 한도가 없어 항상 null"),
+  storefrontRequestsMonthly: limit("스토어프론트 월 트래픽(요청 수, 넘어도 막지 않고 안내만)"),
+  apiLogRetentionDays: limit("API 로그 보관 일수(0이면 API 로그 없음)"),
+  auditLogRetentionDays: limit("감사 로그 보관 일수"),
+  storefrontPreviewHoursMonthly: limit("스토어프론트 편집 미리보기 월 시간"),
+  storefrontBuildMinutesMonthly: limit("스토어프론트 빌드 월 분"),
+  adminApiRequestsMonthly: limit("관리 API 요청 월 포함량(넘으면 속도만 낮춘다, 주문 처리 제외)"),
+});
+export type SubscriptionLimits = z.infer<typeof subscriptionLimitsSchema>;
+
+export const subscriptionUsageSchema = z.object({
+  liveOrders: z.number().int().describe("이번 기간 라이브 주문 수(테스트 결제 주문 제외)"),
+  aiActions: z.number().int().describe("이번 기간 MCP(에이전트) 쓰기(AI 작업) 수"),
+  aiReads: z.number().int().describe("이번 기간 MCP(에이전트) 읽기 수"),
+  storefrontRequests: z.number().int().describe("이번 기간 스토어프론트 요청 수"),
+  adminApiRequests: z
+    .number()
+    .int()
+    .describe("이번 기간 관리 API 요청 수(API 토큰·앱·에이전트 호출, 셀러 콘솔 제외)"),
+  emails: z.number().int().describe("이번 기간 초대·양도 알림 메일 수(한도 없음, 표시만)"),
+  storefrontPreviewMinutes: z.number().int().describe("이번 기간 편집 미리보기 분(끝난 세션)"),
+  storefrontBuildMinutes: z.number().int().describe("이번 기간 빌드 분(끝난 빌드)"),
+  seats: z.number().int().describe("현재 석 수 — 구성원(OWNER 포함) + 대기 중 초대"),
+  customDomains: z.number().int().describe("현재 내 도메인 수(해제한 도메인 제외)"),
+  webhooks: z.number().int().describe("현재 웹훅 구독 수"),
+});
+export type SubscriptionUsage = z.infer<typeof subscriptionUsageSchema>;
+
+export const storeSubscriptionSchema = z.object({
+  plan: z.object({
+    code: responsePlanCodeSchema,
+    name: z.string().describe("요금제 표시 이름(예: 프로)"),
+  }),
+  status: subscriptionStatusSchema,
+  interval: z
+    .enum(["MONTH"])
+    .nullable()
+    .describe("결제 주기. `MONTH`=월간. 요금을 내지 않는 요금제(베타·무료)는 null"),
+  cancelAtPeriodEnd: z.boolean().describe("기간 끝에 해지 예정인가"),
+  period: z
+    .object({
+      start: z.string().describe("사용량 기간 시작(ISO 8601)"),
+      end: z.string().describe("사용량 기간 끝(ISO 8601, 이 시각에 사용량이 초기화된다)"),
+    })
+    .describe("사용량을 세는 기간. 요금을 내지 않는 요금제는 한국 시간 달력 월이다"),
+  limits: subscriptionLimitsSchema,
+  features: z.object({
+    adminApi: z.boolean().describe("관리 API(개인 액세스 토큰·외부 앱 토큰 호출)를 쓸 수 있다"),
+    analytics: z.boolean().describe("애널리틱스 조회를 쓸 수 있다"),
+    storeClone: z.boolean().describe("더 쓰지 않는다 — 스토어 복제 기능을 없애 항상 false"),
+    removeBadge: z.boolean().describe("더 쓰지 않는다 — 배지 키를 없애 항상 false"),
+  }),
+  usage: subscriptionUsageSchema,
+  aiActions: z
+    .object({
+      limit: z.number().int().nullable(),
+      used: z.number().int(),
+      resetsAt: z.string().describe("한도가 초기화되는 시각(ISO 8601)"),
+    })
+    .describe("AI 작업(MCP 쓰기) 한도 요약 — 에이전트가 남은 작업 수를 판단할 때 쓴다"),
+  aiReads: z
+    .object({
+      limit: z.number().int().nullable(),
+      used: z.number().int(),
+      resetsAt: z.string().describe("한도가 초기화되는 시각(ISO 8601)"),
+    })
+    .describe("MCP 읽기 한도 요약"),
+  salesFeePercent: z.literal(0).describe("판매 수수료(%). 모든 요금제 0이다"),
+});
+export type StoreSubscription = z.infer<typeof storeSubscriptionSchema>;
+
+/**
+ * 요금제 한도 오류의 `error.details` — 기존 오류 코드(`STORE_LIMIT_EXCEEDED`·`STOREFRONT_DOMAIN_LIMIT`·`WEBHOOK_LIMIT_EXCEEDED` 등)와
+ * 요금제 오류(`PLAN_LIMIT_EXCEEDED`·`PLAN_AI_ACTIONS_EXCEEDED`·`PLAN_AI_READS_EXCEEDED`·`PLAN_FEATURE_REQUIRED`·`PLAN_API_QUOTA_EXCEEDED`)가 같은 형식을 싣는다.
+ * 모든 필드가 선택이다(기존 코드는 요금제 판정 전 필드만 실을 수 있다).
+ */
+export const planErrorDetailsSchema = z
+  .object({
+    feature: z.string().optional().describe("한도에 닿은 기능 키(예: `limits.ai_actions_monthly`)"),
+    limit: z.number().nullable().optional(),
+    used: z.number().optional(),
+    plan: responsePlanCodeSchema.optional(),
+    resetsAt: z.string().optional().describe("월 한도가 초기화되는 시각(ISO 8601)"),
+    upgradeUrl: z.string().optional().describe("요금제 화면 주소(셀러 콘솔)"),
+    reason: z
+      .string()
+      .optional()
+      .describe(
+        "스토어 수 한도의 이유 — `OWNED_STORES`(소유 스토어 수). `FREE_STORES`는 더 쓰지 않는다",
+      ),
+  })
+  .loose();
+export type PlanErrorDetails = z.infer<typeof planErrorDetailsSchema>;
+
+const limitOrContract = (description: string) =>
+  z.number().int().nullable().describe(`${description}. null이면 계약(엔터프라이즈)·한도 없음`);
+
+/**
+ * 요금제 기능 키 값 — 요금제 비교표·콘솔 요금제 화면이 쓴다. 키는 서버 판정의 기능 키와 같다(추가만 한다). 상위 요금제는 하위 요금제
+ * 기능을 모두 포함한다
+ */
+export const planEntitlementsSchema = z
+  .object({
+    "features.admin_api": z
+      .boolean()
+      .describe(
+        "관리 API(개인 액세스 토큰·외부 앱 토큰 호출). 셀러 콘솔·CLI·MCP는 모든 요금제에서 쓴다",
+      ),
+    "features.analytics": z.boolean().describe("애널리틱스 화면·조회 API"),
+    "limits.ai_reads_monthly": limitOrContract("MCP 읽기 월 한도"),
+    "limits.ai_actions_monthly": limitOrContract(
+      "MCP 쓰기(AI 작업) 월 한도 — 주문 처리는 막지 않는다",
+    ),
+    "limits.custom_domains": limitOrContract("내 도메인 수"),
+    "limits.webhooks": limitOrContract("웹훅 구독 수(0이면 쓸 수 없다)"),
+    "limits.storefront_preview_hours_monthly": limitOrContract("편집 환경 시간(월, 시간)"),
+    "limits.storefront_build_minutes_monthly": limitOrContract("빌드 시간(월, 분)"),
+    "limits.storefront_requests_monthly": limitOrContract(
+      "스토어프론트 월 트래픽(요청 수) — 넘어도 막지 않고 안내만 한다",
+    ),
+    "limits.admin_api_requests_monthly": limitOrContract(
+      "관리 API 월 요청 — 넘으면 속도만 낮춘다(주문 처리 제외)",
+    ),
+    "rate_limit.admin_api": z
+      .number()
+      .nullable()
+      .describe("관리 API 분당 속도 배수(기본 분당 600 × 배수)"),
+    "storefront.cpu_ms": z.number().int().describe("스토어프론트 사이트 요청당 CPU 상한(ms)"),
+    "storefront.subrequests": z
+      .number()
+      .int()
+      .describe("스토어프론트 사이트 요청당 하위 요청 상한"),
+    "storefront.rate_limit_per_minute": z
+      .number()
+      .int()
+      .describe("스토어프론트 남용 방지 요청 속도 상한(사이트당 분당)"),
+    "seats.included": limitOrContract(
+      "포함 구성원 석 — 구성원은 모든 요금제에서 무료·무제한이라 null",
+    ),
+    "retention.analytics_days": z.number().int().describe("애널리틱스 보관 일수"),
+    "retention.api_logs_days": limitOrContract("API 로그 보관 일수(0이면 API 로그 없음)"),
+    "retention.audit_days": limitOrContract("감사 로그 보관 일수"),
+    "support.tier": z
+      .union([z.enum(["COMMUNITY", "EMAIL", "EMAIL_PRIORITY", "DEDICATED", "SLA"]), z.string()])
+      .describe(
+        "지원 등급(`COMMUNITY`·`EMAIL`·`EMAIL_PRIORITY`·`DEDICATED`·`SLA`, 새 등급이 더해질 수 있다)",
+      ),
+  })
+  .describe("요금제 기능 키 값");
+export type PlanEntitlementValues = z.infer<typeof planEntitlementsSchema>;
+
+/** 공개 요금제 한 줄 — `GET /v1/public/plans` */
+export const publicPlanSchema = z.object({
+  code: responsePlanCodeSchema,
+  name: z.string().describe("표시 이름(Free·Pro·프리미엄·엔터프라이즈)"),
+  version: z.number().int().describe("요금제 버전 — 값이 바뀌면 새 버전이 게시된다"),
+  sort: z.number().int(),
+  purchasable: z
+    .boolean()
+    .describe("셀프 결제로 고를 수 있는가(Free·엔터프라이즈는 아니다 — 엔터프라이즈는 계약)"),
+  prices: z.object({
+    currency: z.literal("KRW"),
+    monthly: z.number().int().nullable().describe("월 가격(공급가, 부가세 별도)"),
+    startingAt: z.boolean().describe("「부터」 가격(엔터프라이즈 계약)"),
+    vatIncluded: z
+      .object({
+        monthly: z.number().int().nullable(),
+      })
+      .describe("표시 가격(부가세 포함) — 요금제 비교표는 이 값을 보인다"),
+  }),
+  entitlements: planEntitlementsSchema,
+});
+export type PublicPlan = z.infer<typeof publicPlanSchema>;
+
+/** 요금제 비교표 — `GET /v1/public/plans`(인증 없음, 캐시 가능). 값은 서버가 관리하고 언제든 바뀔 수 있다 */
+export const publicPlansSchema = z.object({
+  vatPercent: z.number().int().describe("부가세율(%)"),
+  plans: z.array(publicPlanSchema).describe("공개 요금제의 지금 버전 — 정렬 순"),
+});
+export type PublicPlans = z.infer<typeof publicPlansSchema>;

package/src/server.ts

@@ -5,8 +5,7 @@
 
 export {
   type DelegatedMemberToken,
-  delegateMemberByEmail,
-  delegateMemberByUid,
+  delegateMember,
   MemberDelegationError,
 } from "./member-delegation";
 export {