@sayren/store-sdk 0.22.0 → 0.28.0

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 {

package/src/session.ts

@@ -9,7 +9,7 @@ import {
 import { type MyAccount, myAccountSchema } from "./schemas/auth";
 
 /**
- * SDK 세션 매니저 — 콘솔(userToken)의 저장·무음 갱신·회전을 캡슐화한다.
+ * SDK 세션 매니저 — 콘솔(액세스 토큰)의 저장·무음 갱신·회전을 캡슐화한다.
  *
  * 저장 매체(쿠키/localStorage/…)와 그 속성(Max-Age·SameSite·Secure·Path)은 **어댑터(앱) 책임**이다.
  * SDK는 "무엇을 어떤 키로 저장할지"만 알고, "어떻게 저장할지"는 SessionStorage 어댑터에 위임한다.
@@ -32,12 +32,28 @@ export const STORE_SESSION_KEYS = {
   pkce: "sayren.store.pkce",
 } as const;
 
+/** 로그아웃 폐기 요청 제한 시간 */
+const REVOKE_TIMEOUT_MS = 5_000;
+
 /** Web Locks 이름 — 탭 간 refresh 회전 직렬화용 */
 const REFRESH_LOCK = STORE_SESSION_KEYS.refresh;
 
+/**
+ * 인가 서버(Sayren 계정, accounts) 주소 — `https://accounts.sayren.app/api/auth/oauth2/{authorize,token,revoke}`.
+ * `resource`를 주면 authorize·code 교환·refresh에 RFC 8707 `resource`를 싣는다(JWT access token의 `aud`).
+ */
+export interface StoreAuthServer {
+  authorizeUrl: string;
+  tokenUrl: string;
+  revokeUrl: string;
+  resource?: string;
+}
+
 export interface StoreSessionOptions {
-  /** 예: https://api.example.com/v1 (/oauth2/token이 덧붙는다) */
+  /** api 주소(예: https://api.example.com/v1) — `userinfo()`의 `GET /me`에 쓴다 */
   baseUrl: string;
+  /** 인가 서버(accounts) 주소들 */
+  authServer: StoreAuthServer;
   /** OAuth public client id (예: avarlabs) */
   clientId: string;
   /** 저장 매체 어댑터 (앱 소유) */
@@ -48,19 +64,19 @@ export interface StoreSessionOptions {
 export interface AuthorizeOptions {
   /** OAuth 콜백 URI (예: https://store.example.com/auth/callback) */
   redirectUri: string;
-  /** 생략 시 서버 기본(stores:read). refresh가 필요하면 offline_access 포함 */
+  /** 생략 시 발급자 기본. refresh가 필요하면 offline_access 포함 */
   scope?: string;
-  /** "signup"이면 authorize 대신 호스티드 회원가입 화면으로 진입한다 */
-  screen?: "authorize" | "signup";
+  /** OIDC `prompt` — `login`(재인증)·`create`(가입)·`consent` */
+  prompt?: "login" | "create" | "consent";
 }
 
 export interface StoreSession {
-  /** 현재 userToken (없으면 null) */
+  /** 현재 액세스 토큰 (없으면 null) */
   getToken(): string | null;
   /** 토큰 저장 + 구독자 통지. refresh_token이 있으면 함께 회전 저장한다(없으면 기존 유지) */
   setTokens(tokens: { access_token: string; refresh_token?: string }): void;
   /**
-   * 무음 세션 갱신 — refresh 토큰으로 새 userToken을 받아 회전 저장한다.
+   * 무음 세션 갱신 — refresh 토큰으로 새 액세스 토큰을 받아 회전 저장한다.
    * - 탭 내부: 동시 다발 호출을 single-flight로 합친다.
    * - 탭 간: navigator.locks(있으면)로 회전을 직렬화하고, 락 진입 시 다른 탭이 이미
    *   회전했으면(세션 토큰 변경) 내 refresh 토큰을 소비하지 않고 true를 반환한다.
@@ -68,11 +84,17 @@ export interface StoreSession {
    * 회전이 실패(만료·재사용 폐기)하면 세션을 clear하고 false. (401 경로는 onUnauthorized→clear가 별도 처리.)
    */
   refresh(): Promise<boolean>;
-  /** 세션/리프레시 키를 지우고 구독자에게 통지한다 */
+  /** 세션/리프레시 키를 지우고 구독자에게 통지한다(서버의 토큰은 그대로다 — 로그아웃은 `logout()`) */
   clear(): void;
+  /**
+   * 로그아웃 — 인가 서버에서 **refresh 토큰(패밀리째)과 access 토큰을 폐기**(`revokeUrl`, RFC 7009)한 뒤 세션을 지운다.
+   * refresh를 폐기하지 않으면 쿠키만 지워도 서버의 refresh 패밀리가 절대 만료까지 살아 있어, 새어 나간 refresh 토큰으로
+   * 계속 새 액세스 토큰을 받을 수 있다. 폐기 요청 실패(네트워크·이미 무효)는 무시하고 세션은 항상 지운다.
+   */
+  logout(): Promise<void>;
   /** 변경 구독(useSyncExternalStore 소비용) — getToken을 스냅샷으로 쓴다. 해지 함수 반환 */
   subscribe(cb: () => void): () => void;
-  /** 현재 userToken (getToken()과 동일 — 게터 형태 소비용) */
+  /** 현재 액세스 토큰 (getToken()과 동일 — 게터 형태 소비용) */
   readonly accessToken: string | null;
   /** 현재 저장된 refresh 토큰 (없으면 null) */
   readonly refreshToken: string | null;
@@ -92,7 +114,8 @@ export interface StoreSession {
 }
 
 export function createStoreSession(options: StoreSessionOptions): StoreSession {
-  const { baseUrl, clientId, storage } = options;
+  const { baseUrl, clientId, storage, authServer } = options;
+  const { revokeUrl, tokenUrl, resource } = authServer;
   const fetchFn = options.fetch ?? globalThis.fetch;
   const listeners = new Set<() => void>();
 
@@ -116,6 +139,37 @@ export function createStoreSession(options: StoreSessionOptions): StoreSession {
     notify();
   }
 
+  /** RFC 7009 — 무효 토큰이어도 200이다. 실패는 호출부가 무시한다. 응답이 늦어도 로그아웃이 멈추지 않게 5초로 끊는다 */
+  async function revokeToken(token: string): Promise<void> {
+    await fetchFn(revokeUrl, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ token, client_id: clientId }).toString(),
+      // AbortSignal.timeout이 없는 브라우저는 제한 없이 보낸다(로그아웃은 그래도 진행된다)
+      signal:
+        typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function"
+          ? AbortSignal.timeout(REVOKE_TIMEOUT_MS)
+          : undefined,
+    });
+  }
+
+  async function logout(): Promise<void> {
+    // 진행 중인 갱신이 있으면 끝나기를 기다린다 — 그 사이 회전된 새 refresh 토큰을 폐기해야 한다(옛 토큰만 폐기하면 새 패밀리 토큰이 남는다)
+    if (refreshInFlight) await refreshInFlight.catch(() => false);
+    const refreshToken = storage.get(STORE_SESSION_KEYS.refresh);
+    const accessToken = getToken();
+    // refresh 먼저 — 패밀리를 폐기해야 새 액세스 토큰 발급이 끊긴다. access는 남은 수명 동안의 사용을 끊는다
+    for (const token of [refreshToken, accessToken]) {
+      if (!token) continue;
+      try {
+        await revokeToken(token);
+      } catch {
+        // 네트워크 실패여도 로그아웃은 진행한다
+      }
+    }
+    clear();
+  }
+
   let refreshInFlight: Promise<boolean> | null = null;
 
   function refresh(): Promise<boolean> {
@@ -140,7 +194,13 @@ export function createStoreSession(options: StoreSessionOptions): StoreSession {
     const refreshToken = storage.get(STORE_SESSION_KEYS.refresh);
     if (!refreshToken) return false;
     try {
-      const tokens = await refreshUserToken({ baseUrl, clientId, refreshToken, fetch: fetchFn });
+      const tokens = await refreshUserToken({
+        clientId,
+        refreshToken,
+        tokenUrl,
+        resource,
+        fetch: fetchFn,
+      });
       setTokens({ access_token: tokens.access_token, refresh_token: tokens.refresh_token });
       return true;
     } catch {
@@ -178,20 +238,16 @@ export function createStoreSession(options: StoreSessionOptions): StoreSession {
     const blob: PkceBlob = { 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();
+    const finalUrl = buildAuthorizeUrl({
+      authorizeUrl: authServer.authorizeUrl,
+      clientId,
+      redirectUri: authorizeOptions.redirectUri,
+      state,
+      codeChallenge: challenge,
+      scope: authorizeOptions.scope,
+      resource,
+      prompt: authorizeOptions.prompt,
+    });
 
     if (typeof window !== "undefined") {
       window.location.assign(finalUrl);
@@ -209,11 +265,12 @@ export function createStoreSession(options: StoreSessionOptions): StoreSession {
       throw new Error("state가 일치하지 않습니다. 다시 시도해주십시오");
     }
     const tokens = await exchangeAuthorizationCode({
-      baseUrl,
       clientId,
       redirectUri: saved.redirectUri,
       code,
       codeVerifier: saved.verifier,
+      tokenUrl,
+      resource,
       fetch: fetchFn,
     });
     setTokens({ access_token: tokens.access_token, refresh_token: tokens.refresh_token });
@@ -235,6 +292,7 @@ export function createStoreSession(options: StoreSessionOptions): StoreSession {
     setTokens,
     refresh,
     clear,
+    logout,
     subscribe,
     authorize,
     handleCallback,

package/src/schemas/api-client.ts

@@ -1,121 +0,0 @@
-import { z } from "zod";
-
-/**
- * 앱(OAuth 클라이언트) 관리 — `/v1/store/api-clients` (auth-spec 부록 B-13).
- * 등록은 DCR(`POST /v1/oauth2/register`, RFC 7591)이 담당하고, 이 스키마는 등록 이후의
- * 목록·상세·시크릿 재발급·비활성화 응답 계약이다. 시크릿 해시는 어떤 응답에도 포함되지 않는다.
- */
-
-export const apiClientTypeSchema = z
-  .enum(["public", "confidential"])
-  .describe(
-    "클라이언트 유형. `public`=시크릿 없음(PKCE 로그인용), `confidential`=시크릿 보유(서버 간 연동용)",
-  );
-export type ApiClientType = z.infer<typeof apiClientTypeSchema>;
-
-export const apiClientStatusSchema = z
-  .enum(["ACTIVE", "REVOKED"])
-  .describe("상태. `REVOKED`는 비활성화된 클라이언트이며 다시 활성화할 수 없다");
-export type ApiClientStatus = z.infer<typeof apiClientStatusSchema>;
-
-export 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"),
-});
-export type ApiClient = z.infer<typeof apiClientSchema>;
-
-/** 시크릿 재발급 응답 — 평문 시크릿은 이 응답에서 단 한 번만 노출된다 */
-export const apiClientSecretRotatedSchema = apiClientSchema.extend({
-  clientSecret: z
-    .string()
-    .describe("새 클라이언트 시크릿 평문. 이 응답에서만 노출되며 다시 조회할 수 없다"),
-});
-export type ApiClientSecretRotated = z.infer<typeof apiClientSecretRotatedSchema>;
-
-export const apiClientListQuerySchema = z.object({
-  status: apiClientStatusSchema.optional().describe("상태 필터. 생략하면 전체"),
-});
-export type ApiClientListParams = z.infer<typeof apiClientListQuerySchema>;
-
-/**
- * Dynamic Client Registration 요청 (RFC 7591 §2, auth-spec §12) — `POST /v1/oauth2/register`.
- * OAuth 프로토콜 표면이라 필드명이 snake_case이고 응답·등록 오류는 평면 JSON이다.
- * 생략한 필드는 서버 기본값을 따른다(SDK가 기본값을 채워 보내지 않는다).
- */
-export 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`",
-    ),
-});
-export type OAuthClientRegistrationRequest = z.infer<typeof oauthClientRegistrationRequestSchema>;
-
-/** Dynamic Client Registration 응답 (RFC 7591 §3.2.1) — client_secret은 이 응답에서만 노출된다 */
-export 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("부여된 스코프 (공백 구분)"),
-});
-export type OAuthClientRegistrationResponse = z.infer<typeof oauthClientRegistrationResponseSchema>;