@sayren/store-sdk 0.30.7 → 0.30.9

package/src/schemas/apps.ts

@@ -0,0 +1,310 @@
+import { z } from "zod";
+import {
+  type AppCapabilities,
+  appEventTypeSchema,
+  appHandleSchema,
+  appSettingFieldSchema,
+} from "./app-manifest";
+
+/**
+ * 설치 앱 관리 API 계약 (이슈 #22) — `/v1/apps/installations/**`(상점이 설치한 앱), `/v1/app/installation`(설치 토큰 자기 조회).
+ * 개발자 API(`/platform/v1/developer/**`)는 플랫폼 플레인이라 여기 두지 않는다.
+ */
+
+/** 배포 범위 — `PRIVATE_OWN` 개발자 조직 구성원이 OWNER·ADMIN인 상점과 개발 상점(A1) · `PRIVATE_LINK` 설치 링크(A2) · `LISTED` 공개 목록(A3) */
+export const appDistributionSchema = z.enum(["PRIVATE_OWN", "PRIVATE_LINK", "LISTED"]);
+export type AppDistribution = z.infer<typeof appDistributionSchema>;
+
+export const appRuntimeSchema = z.enum(["CODE", "EXTERNAL"]);
+export type AppRuntime = z.infer<typeof appRuntimeSchema>;
+
+/** 앱 상태 — `SUSPENDED`는 운영자 정지(모든 설치 토큰·실행 거부, 설치 행은 그대로) */
+export const appStatusSchema = z.enum(["ACTIVE", "SUSPENDED", "DELETED"]);
+export type AppStatus = z.infer<typeof appStatusSchema>;
+
+export const appInstallationStatusSchema = z.enum(["ACTIVE", "UNINSTALLED", "SUSPENDED"]);
+export type AppInstallationStatus = z.infer<typeof appInstallationStatusSchema>;
+
+/** 설치 앱의 앱 정보 — 상점이 보는 범위만(개발자 비밀 값·소스·빌드는 없다) */
+export const appInstallationAppSchema = z.object({
+  appId: z.string(),
+  handle: z.string().describe("앱 handle. 앱 화면 주소의 라벨"),
+  name: z.string(),
+  iconUrl: z.string().nullable(),
+  description: z.string().nullable(),
+  developerName: z.string().describe("개발자 조직 이름"),
+  supportEmail: z.string().nullable(),
+  distribution: appDistributionSchema,
+  runtime: appRuntimeSchema,
+  status: appStatusSchema,
+});
+export type AppInstallationApp = z.infer<typeof appInstallationAppSchema>;
+
+const settingsValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+
+/** 설치 설정 — 비밀 필드 값은 가려서 준다(앞 4자 + `…`). 비어 있는 필드는 null */
+export const appInstallationSettingsSchema = z.object({
+  fields: z.record(z.string(), appSettingFieldSchema).describe("실행 버전 매니페스트의 설정 필드"),
+  values: z.record(z.string(), settingsValueSchema),
+  /** 필수 설정이 모두 채워졌는가 — 아니면 이벤트 함수를 부르지 않는다 */
+  configured: z.boolean(),
+  updatedAt: z.string().nullable(),
+});
+export type AppInstallationSettings = z.infer<typeof appInstallationSettingsSchema>;
+
+/** 설정 저장 — 비밀 필드를 생략하면 현재 값을 유지한다. null은 비운다 */
+export const appInstallationSettingsUpdateSchema = z.object({
+  values: z.record(z.string(), settingsValueSchema),
+});
+export type AppInstallationSettingsUpdate = z.infer<typeof appInstallationSettingsUpdateSchema>;
+
+export const appInstallationSchema = z.object({
+  installationId: z.string(),
+  storeId: z.string(),
+  app: appInstallationAppSchema,
+  status: appInstallationStatusSchema,
+  versionNumber: z.number().int().describe("실행 중인 앱 버전"),
+  pendingVersionNumber: z
+    .number()
+    .int()
+    .nullable()
+    .describe("재동의가 필요한 새 버전. 없으면 null"),
+  grantedScopes: z.array(z.string()).describe("동의한 스코프"),
+  grantedNetworkHosts: z.array(z.string()).describe("동의한 외부 호출 호스트"),
+  events: z.array(appEventTypeSchema).describe("이 설치가 받는 이벤트"),
+  adminPage: z.boolean().describe("상점 플랫폼 앱 화면이 있는가"),
+  /** 설치 결과의 캐시가 아니라 실행 버전 매니페스트의 요약 */
+  settings: appInstallationSettingsSchema,
+  installedBy: z.object({ userId: z.string(), name: z.string().nullable() }).nullable(),
+  installedAt: z.string(),
+  uninstalledAt: z.string().nullable(),
+  updatedAt: z.string(),
+});
+export type AppInstallation = z.infer<typeof appInstallationSchema>;
+
+/** `POST /v1/apps/installations` — accounts 설치 동의 결과(1회용 JWT)를 낸다(상점 플랫폼 전용) */
+export const appInstallRequestSchema = z.object({
+  result: z.string().min(1).describe("accounts가 발급한 설치 결과 JWT(`typ: sayren-install+jwt`)"),
+});
+export type AppInstallRequest = z.infer<typeof appInstallRequestSchema>;
+
+/** `POST /v1/apps/installations/{id}/session` — 앱 화면 iframe이 쓸 세션 토큰(5분) */
+export const appSessionSchema = z.object({
+  token: z.string(),
+  expiresAt: z.string(),
+  appOrigin: z.url().describe("iframe 주소의 origin(`https://{handle}.{앱 도메인}`)"),
+});
+export type AppSession = z.infer<typeof appSessionSchema>;
+
+/** `GET /v1/app/installation` — 설치 토큰으로 보는 자기 설치 */
+export const appInstallationSelfSchema = z.object({
+  installationId: z.string(),
+  appId: z.string(),
+  storeId: z.string(),
+  storeName: z.string(),
+  versionNumber: z.number().int(),
+  grantedScopes: z.array(z.string()),
+  installedAt: z.string(),
+});
+export type AppInstallationSelf = z.infer<typeof appInstallationSelfSchema>;
+
+export type { AppCapabilities };
+
+// ─── 개발자 API (플랫폼 플레인 `/platform/v1/developer/**`, 공개 문서 제외 — CLI·상점 플랫폼 개발자 화면이 쓴다) ───
+
+export const developerOrgSchema = z.object({
+  orgId: z.string(),
+  name: z.string(),
+  role: z.enum(["OWNER", "MEMBER"]),
+});
+export type DeveloperOrg = z.infer<typeof developerOrgSchema>;
+
+export const appVersionStatusSchema = z.enum(["BUILDING", "READY", "FAILED", "REVOKED"]);
+export type AppVersionStatus = z.infer<typeof appVersionStatusSchema>;
+
+/** 빌드 단계(매뉴얼 「앱 버전과 배포 › 빌드」). 로컬 번들(A1)은 `DEPENDENCIES`·`VERIFY`·`BUNDLE`·`UPLOAD`를 서버가 돈다 */
+export const appBuildStageSchema = z.enum([
+  "DEPENDENCIES",
+  "VERIFY",
+  "INSTALL",
+  "TYPECHECK",
+  "BUILD",
+  "BUNDLE",
+  "UPLOAD",
+]);
+export type AppBuildStage = z.infer<typeof appBuildStageSchema>;
+
+export const appBuildSchema = z.object({
+  buildId: z.string(),
+  status: z.enum(["QUEUED", "RUNNING", "SUCCEEDED", "FAILED", "TIMED_OUT"]),
+  stages: z.array(z.object({ stage: z.string(), ok: z.boolean(), durationMs: z.number() })),
+  failureStage: z.string().nullable(),
+  errorCode: z.string().nullable(),
+  logTail: z.string().nullable(),
+  /** 의존성 검사 결과(거절·경고). 검사 전이면 null */
+  dependencies: z
+    .object({
+      rejected: z.array(z.record(z.string(), z.unknown())),
+      warnings: z.array(z.record(z.string(), z.unknown())),
+    })
+    .nullable(),
+  createdAt: z.string(),
+  finishedAt: z.string().nullable(),
+});
+export type AppBuild = z.infer<typeof appBuildSchema>;
+
+export const appVersionSchema = z.object({
+  versionId: z.string(),
+  number: z.number().int(),
+  status: appVersionStatusSchema,
+  current: z.boolean().describe("앱의 현재 버전(release한 버전)인가"),
+  message: z.string().nullable(),
+  capabilities: z.object({
+    scopes: z.array(z.string()),
+    events: z.array(z.string()),
+    networkHosts: z.array(z.string()),
+    adminPage: z.boolean(),
+    requiredSettings: z.array(z.string()),
+    secretSettings: z.array(z.string()),
+  }),
+  build: appBuildSchema.nullable(),
+  releasedAt: z.string().nullable(),
+  revokedAt: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type AppVersion = z.infer<typeof appVersionSchema>;
+
+export const developerAppSchema = z.object({
+  appId: z.string(),
+  orgId: z.string(),
+  handle: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  iconUrl: z.string().nullable(),
+  supportEmail: z.string().nullable(),
+  distribution: appDistributionSchema,
+  runtime: appRuntimeSchema,
+  status: appStatusSchema,
+  suspendedReason: z.string().nullable(),
+  currentVersionNumber: z.number().int().nullable(),
+  installations: z.object({
+    active: z.number().int(),
+    pendingReconsent: z.number().int(),
+  }),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type DeveloperApp = z.infer<typeof developerAppSchema>;
+
+export const developerAppCreateSchema = z.object({
+  handle: appHandleSchema,
+  name: z.string().trim().min(1).max(60),
+  description: z.string().trim().max(500).optional(),
+});
+export type DeveloperAppCreate = z.infer<typeof developerAppCreateSchema>;
+
+/** `PUT /platform/v1/developer/apps/{appId}/versions` — CLI `app deploy`가 올리는 번들 */
+export const appArtifactUploadSchema = z.object({
+  manifest: z.unknown().describe("sayren.app.json 원문(JSON)"),
+  packageJson: z.string().max(256 * 1024),
+  lockfile: z
+    .string()
+    .max(4 * 1024 * 1024)
+    .nullable(),
+  /** 서버 번들(ESM 한 파일) base64. gzip 3MB까지 */
+  server: z.string().min(1),
+  ui: z
+    .array(z.object({ path: z.string().min(1).max(512), content: z.string() }))
+    .max(2_000)
+    .default([]),
+  message: z.string().trim().max(200).optional(),
+});
+export type AppArtifactUpload = z.infer<typeof appArtifactUploadSchema>;
+
+export const appReleaseResultSchema = z.object({
+  version: appVersionSchema,
+  /** release가 곧바로 적용된 설치 수 */
+  applied: z.number().int(),
+  /** 넓어진 범위라 재동의를 기다리는 설치 수 */
+  pendingReconsent: z.number().int(),
+});
+export type AppReleaseResult = z.infer<typeof appReleaseResultSchema>;
+
+export const appSecretSummarySchema = z.object({
+  name: z.string(),
+  updatedAt: z.string(),
+});
+export type AppSecretSummary = z.infer<typeof appSecretSummarySchema>;
+
+export const devStoreSchema = z.object({
+  storeId: z.string(),
+  name: z.string(),
+  storeCode: z.string(),
+  status: z.enum(["ACTIVE", "SUSPENDED", "CLOSED"]),
+  createdAt: z.string(),
+});
+export type DevStore = z.infer<typeof devStoreSchema>;
+
+/** 개발자가 보는 설치 한 줄 */
+export const developerInstallationSchema = z.object({
+  installationId: z.string(),
+  storeId: z.string(),
+  storeName: z.string(),
+  status: appInstallationStatusSchema,
+  versionNumber: z.number().int().nullable(),
+  pendingVersionNumber: z.number().int().nullable(),
+  installedAt: z.string(),
+});
+export type DeveloperInstallation = z.infer<typeof developerInstallationSchema>;
+
+/** `POST /platform/v1/developer/apps/{appId}/dev-token` — `sayren app dev`가 쓰는 설치 토큰(1시간) */
+export const appDevTokenSchema = z.object({
+  token: z.string(),
+  expiresAt: z.string(),
+  installationId: z.string(),
+  storeId: z.string(),
+});
+export type AppDevToken = z.infer<typeof appDevTokenSchema>;
+
+/** 호출 기록 한 건(개발자 로그) */
+export const appInvocationSchema = z.object({
+  invocationId: z.string(),
+  storeId: z.string(),
+  storeName: z.string().nullable(),
+  installationId: z.string(),
+  versionNumber: z.number().int().nullable(),
+  kind: z.enum(["event", "http", "schedule"]),
+  eventType: z.string().nullable(),
+  outcome: z.enum(["OK", "ERROR", "LIMIT_EXCEEDED", "REJECTED"]),
+  errorMessage: z.string().nullable(),
+  cpuMs: z.number().nullable(),
+  durationMs: z.number(),
+  /** `console.*`·`ctx.log.*` 줄(최대 100줄, 줄마다 500자) */
+  logs: z.array(z.object({ level: z.string(), message: z.string() })),
+  createdAt: z.string(),
+});
+export type AppInvocation = z.infer<typeof appInvocationSchema>;
+
+/** 앱 배포 키(developer.sayren.app 「키 발행」) — 값은 만들 때 한 번만 보인다 */
+export const appDeployKeySchema = z.object({
+  keyId: z.string(),
+  name: z.string(),
+  prefix: z.string().describe("값 앞 12자"),
+  createdAt: z.string(),
+  lastUsedAt: z.string().nullable(),
+});
+export type AppDeployKey = z.infer<typeof appDeployKeySchema>;
+
+export const appDeployKeyCreatedSchema = appDeployKeySchema.extend({
+  /** 전체 값 — 이때만 보인다 */
+  value: z.string(),
+});
+export type AppDeployKeyCreated = z.infer<typeof appDeployKeyCreatedSchema>;
+
+export const appDeployKeyCreateSchema = z.object({
+  name: z.string().trim().min(1).max(60),
+});
+
+/** 배포 키 값 형식 — `sak_{appId 뒤}_{32 hex}` */
+export const APP_DEPLOY_KEY_PATTERN = /^sak_[a-z0-9]{8,40}_[0-9a-f]{32}$/;
+export const APP_DEPLOY_KEY_PREFIX = "sak_";

package/src/schemas/misc.ts

@@ -215,9 +215,22 @@ export const webhookDeliveryStatusSchema = z
 export type WebhookDeliveryStatus = z.infer<typeof webhookDeliveryStatusSchema>;
 
 export const webhookDeliveryErrorCodeSchema = z
-  .enum(["TIMEOUT", "CONNECTION_FAILED", "BLOCKED_ADDRESS", "NON_2XX", "WEBHOOK_SUSPENDED"])
+  .enum([
+    "TIMEOUT",
+    "CONNECTION_FAILED",
+    "BLOCKED_ADDRESS",
+    "NON_2XX",
+    "WEBHOOK_SUSPENDED",
+    "APP_ERROR",
+    "APP_LIMIT_EXCEEDED",
+    "APP_REJECTED",
+    "APP_UNCONFIGURED",
+    "APP_INACTIVE",
+    "APP_RUNNER_UNAVAILABLE",
+  ])
   .describe(
-    "전송 실패 사유. `TIMEOUT`=10초 안에 응답 없음, `CONNECTION_FAILED`=연결 실패(DNS·TLS 포함), `BLOCKED_ADDRESS`=사설·루프백 등 전송이 허용되지 않는 주소, `NON_2XX`=2xx가 아닌 응답(리다이렉트 포함), `WEBHOOK_SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨",
+    "전송 실패 사유. `TIMEOUT`=10초 안에 응답 없음, `CONNECTION_FAILED`=연결 실패(DNS·TLS 포함), `BLOCKED_ADDRESS`=사설·루프백 등 전송이 허용되지 않는 주소, `NON_2XX`=2xx가 아닌 응답(리다이렉트 포함), `WEBHOOK_SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨. " +
+      "설치 앱(#22): `APP_ERROR`=앱 코드 예외, `APP_LIMIT_EXCEEDED`=CPU·요청·시간 한도 초과, `APP_REJECTED`=앱·버전 정지 등으로 거부, `APP_UNCONFIGURED`=필수 설정이 비어 보내지 않음, `APP_INACTIVE`=설치가 제거됨, `APP_RUNNER_UNAVAILABLE`=실행 환경 호출 실패",
   );
 export type WebhookDeliveryErrorCode = z.infer<typeof webhookDeliveryErrorCodeSchema>;
 

package/src/schemas/payment.ts

@@ -270,11 +270,14 @@ export const liveGateConditionCodeSchema = z
     "SANDBOX_REFUND",
     "LIVE_CONNECTION",
     "PLATFORM_LIVE_ENABLED",
+    "NOT_TEMPLATE_STORE",
+    "NOT_DEVELOPMENT_STORE",
   ])
   .describe(
     "라이브 개방 조건. `TEST_CONNECTION`=TEST 세트 연결 테스트 성공, `SANDBOX_PAYMENT`=현재 TEST 세트로 샌드박스 결제 1건 승인, " +
       "`SANDBOX_REFUND`=그 샌드박스 결제의 환불 1건 성공, `LIVE_CONNECTION`=LIVE 세트 연결 테스트 성공, " +
-      "`PLATFORM_LIVE_ENABLED`=플랫폼이 실결제를 열어 둠",
+      "`PLATFORM_LIVE_ENABLED`=플랫폼이 실결제를 열어 둠, `NOT_TEMPLATE_STORE`=템플릿 상점이 아님(템플릿 상점에만 싣고 늘 미충족), " +
+      "`NOT_DEVELOPMENT_STORE`=앱 개발 상점이 아님(앱 개발 상점에만 싣고 늘 미충족)",
   );
 export type LiveGateConditionCode = z.infer<typeof liveGateConditionCodeSchema>;
 

package/src/schemas/scope-descriptions.ts

@@ -0,0 +1,34 @@
+import { STORE_SCOPE_RESOURCES, type StoreScopeResource } from "./scope";
+
+/**
+ * 스코프를 사람이 읽는 문장 (이슈 #22) — 앱 설치 동의 화면(accounts), 상점 플랫폼 설치 앱 권한 표시, 유저 문서 스코프 레퍼런스가
+ * 같은 문장을 쓴다. 읽기(`r`)와 쓰기(`rw`)를 따로 둔다 — 동의 화면은 쓰기를 강조한다.
+ */
+export const SCOPE_DESCRIPTIONS: Record<StoreScopeResource, { r: string; rw: string }> = {
+  product: { r: "상품 정보를 읽습니다", rw: "상품을 만들고 수정합니다" },
+  category: { r: "카테고리를 읽습니다", rw: "카테고리를 만들고 수정합니다" },
+  order: { r: "주문을 읽습니다", rw: "주문 상태를 바꿉니다(발송·배송완료·취소 등)" },
+  claim: { r: "취소·반품·교환 요청을 읽습니다", rw: "취소·반품·교환을 처리합니다" },
+  inquiry: { r: "상품 문의를 읽습니다", rw: "상품 문의에 답합니다" },
+  review: { r: "리뷰를 읽습니다", rw: "리뷰를 관리합니다" },
+  settlement: { r: "매출 리포트를 읽습니다", rw: "매출 리포트를 읽습니다" },
+  analytics: { r: "방문·구매 분석 데이터를 읽습니다", rw: "방문·구매 분석 데이터를 읽습니다" },
+  webhook: { r: "웹훅 설정을 읽습니다", rw: "웹훅을 만들고 수정합니다" },
+  store: { r: "상점 정보를 읽습니다", rw: "상점 설정을 수정합니다" },
+  member: { r: "구성원 목록을 읽습니다", rw: "구성원을 초대하고 역할을 바꿉니다" },
+  customer: { r: "고객 정보(이름·연락처·주소)를 읽습니다", rw: "고객 정보를 수정합니다" },
+  audit: { r: "감사 로그를 읽습니다", rw: "감사 로그를 읽습니다" },
+  promotion: { r: "쿠폰·적립금 설정을 읽습니다", rw: "쿠폰을 발급하고 적립금을 지급합니다" },
+  storefront: { r: "스토어프론트 설정을 읽습니다", rw: "스토어프론트를 편집하고 발행합니다" },
+  flow: { r: "주문 흐름 설정을 읽습니다", rw: "주문 흐름을 만들고 수정합니다" },
+};
+
+/** `{resource}:{r|rw}` → 문장. 카탈로그에 없는 스코프는 null */
+export function describeScope(scope: string): string | null {
+  const [resource, access] = scope.split(":");
+  if (!resource || !(resource in STORE_SCOPE_RESOURCES)) return null;
+  const allowed = STORE_SCOPE_RESOURCES[resource as StoreScopeResource] as readonly string[];
+  if (access !== "r" && access !== "rw") return null;
+  if (!allowed.includes(access)) return null;
+  return SCOPE_DESCRIPTIONS[resource as StoreScopeResource][access];
+}

package/src/schemas/starter.ts

@@ -0,0 +1,173 @@
+import { z } from "zod";
+
+/**
+ * 쇼핑몰 시작(starter, 이슈 #122) — 원격 MCP의 starter 절차가 쓰는 브랜드 브리프와 진행 상태.
+ *
+ * 공개 OpenAPI 문서에는 싣지 않는다(절차를 운영 테스트로 다듬는 동안 계약이 바뀔 수 있다). 소비자는 sayren MCP 도구다.
+ */
+
+/** 판매 품목 — 빠른 시작(#70) 답과 템플릿 카탈로그 `recommendFor`가 같은 코드를 쓴다 */
+export const storeIndustrySchema = z.enum(["FASHION", "FOOD", "DIGITAL", "OTHER"]);
+export type StoreIndustry = z.infer<typeof storeIndustrySchema>;
+
+/** 상품 자료 — 인터뷰의 「상품 자료」 답. 상품 등록 단계의 방법을 고른다 */
+export const brandBriefProductSourceSchema = z.enum([
+  "SPREADSHEET",
+  "EXISTING_STORE",
+  "PHOTOS",
+  "NONE",
+]);
+export type BrandBriefProductSource = z.infer<typeof brandBriefProductSourceSchema>;
+
+export const BRAND_BRIEF_MAX_REFERENCES = 5;
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "https:" || protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+/** 참고 사이트 — 이미지는 저장하지 않고 주소와 에이전트가 쓴 레이아웃 요약만 둔다 */
+export const brandBriefReferenceSchema = z.object({
+  url: z
+    .string()
+    .trim()
+    .max(2048)
+    .refine(isHttpUrl, {
+      message: "http(s) 주소여야 합니다",
+    })
+    .describe("참고 사이트 주소"),
+  summary: z
+    .string()
+    .trim()
+    .min(1)
+    .max(1000)
+    .describe("레이아웃 특징 요약 (헤더 형태·홈 섹션 순서·상세 구성 등)"),
+});
+export type BrandBriefReference = z.infer<typeof brandBriefReferenceSchema>;
+
+/** 브랜드 브리프 — starter 인터뷰 결과. 이후 단계(화면 설정·상품·다듬기)의 판단 근거다 */
+export const brandBriefSchema = z.object({
+  industry: storeIndustrySchema.nullable().describe("판매 품목"),
+  mood: z.string().trim().max(200).nullable().describe("쇼핑몰 분위기 (예: 깔끔한, 따뜻한)"),
+  pointColor: z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식이어야 합니다")
+    .nullable()
+    .describe("대표 색 (`#RRGGBB`)"),
+  references: z.array(brandBriefReferenceSchema).max(BRAND_BRIEF_MAX_REFERENCES),
+  productSource: brandBriefProductSourceSchema.nullable().describe("상품 자료"),
+  notes: z
+    .string()
+    .trim()
+    .max(4000)
+    .nullable()
+    .describe("인터뷰 메모 (타깃 고객, 판매 방식, 셀러가 강조한 요구)"),
+});
+export type BrandBrief = z.infer<typeof brandBriefSchema>;
+
+/** `PUT /v1/storefront/brand-brief` — 브리프 전체를 바꾼다. 생략한 항목은 비운다 */
+export const putBrandBriefRequestSchema = z.object({
+  industry: storeIndustrySchema.nullable().default(null),
+  mood: z.string().trim().max(200).nullable().default(null),
+  pointColor: z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식이어야 합니다")
+    .nullable()
+    .default(null),
+  references: z.array(brandBriefReferenceSchema).max(BRAND_BRIEF_MAX_REFERENCES).default([]),
+  productSource: brandBriefProductSourceSchema.nullable().default(null),
+  notes: z.string().trim().max(4000).nullable().default(null),
+});
+export type PutBrandBriefRequest = z.input<typeof putBrandBriefRequestSchema>;
+
+/** `GET·PUT /v1/storefront/brand-brief` 응답 — 저장한 적이 없으면 `brief`·`updatedAt`이 null이다 */
+export const brandBriefViewSchema = z.object({
+  brief: brandBriefSchema.nullable(),
+  updatedAt: z.string().nullable(),
+});
+export type BrandBriefView = z.infer<typeof brandBriefViewSchema>;
+
+/**
+ * starter 단계 — 서버 상태로 계산한다(에이전트 보고가 아니다). 앞 단계가 끝나지 않았으면 그 단계다.
+ * `POLISH`(다듬기·구조 감사·구매 여정 점검)부터는 로컬 검사와 셀러 확인이 판정하므로 서버는 더 나누지 않는다.
+ */
+export const STARTER_STAGES = [
+  "INTERVIEW",
+  "SITE",
+  "STORE_INFO",
+  "PRODUCTS",
+  "SELLER_TASKS",
+  "POLISH",
+] as const;
+export const starterStageSchema = z.enum(STARTER_STAGES);
+export type StarterStage = z.infer<typeof starterStageSchema>;
+
+/** 셀러가 상점 플랫폼에서 직접 하는 항목 — 결제는 연결 여부만 본다(테스트·라이브를 가리지 않는다) */
+export const STARTER_SELLER_TASKS = [
+  "PAYMENT_CONNECTED",
+  "BUSINESS_INFO",
+  "SHIPPING_POLICY",
+] as const;
+export const starterSellerTaskSchema = z.enum(STARTER_SELLER_TASKS);
+export type StarterSellerTask = z.infer<typeof starterSellerTaskSchema>;
+
+/** 상점 기본 정보 항목 — 고객센터 번호만 필수이고 로고는 권장이다(셀러가 로고가 없다고 하면 만들지 않는다) */
+export const starterStoreInfoFieldSchema = z.enum(["LOGO", "CUSTOMER_CENTER_PHONE"]);
+
+/** `GET /v1/storefront/starter` — starter 진행 상태 */
+export const starterStatusSchema = z.object({
+  stage: starterStageSchema,
+  hostingEnabled: z.boolean().describe("새 호스팅 사이트를 만들 수 있는가"),
+  defaultSiteUrl: z
+    .string()
+    .nullable()
+    .describe(
+      "사이트를 만들면 쓰는 기본 주소(`https://{상점 코드}.{호스팅 도메인}`). 사이트가 있으면 null",
+    ),
+  brief: z.object({
+    saved: z.boolean(),
+    updatedAt: z.string().nullable(),
+  }),
+  site: z
+    .object({
+      siteId: z.string(),
+      url: z.string(),
+      templateId: z.string(),
+      visibility: z.enum(["COMING_SOON", "PUBLIC"]),
+      status: z.string(),
+      synced: z.boolean().describe("발행 상태가 공개 주소에 반영됐는가"),
+      publishedVersion: z
+        .object({
+          versionId: z.string(),
+          templateVersion: z.string(),
+          createdVia: z.string().nullable(),
+          publishedAt: z.string().nullable(),
+        })
+        .nullable(),
+    })
+    .nullable(),
+  storeInfo: z.object({
+    done: z.boolean().describe("필수 항목(고객센터 번호)이 모두 있는가"),
+    missing: z.array(starterStoreInfoFieldSchema).describe("비어 있는 필수 항목"),
+    suggested: z
+      .array(starterStoreInfoFieldSchema)
+      .describe("비어 있지만 완료를 막지 않는 항목(로고). 셀러가 원할 때만 채운다"),
+  }),
+  products: z.object({
+    realCount: z.number().int().min(0).describe("샘플이 아닌 판매 중 상품 수"),
+  }),
+  sellerTasks: z.array(z.object({ key: starterSellerTaskSchema, done: z.boolean() })),
+  checkout: z.object({
+    available: z.boolean(),
+    mode: z.enum(["TEST", "LIVE"]).nullable(),
+    reason: z.enum(["PAYMENT_NOT_CONFIGURED", "PAYMENT_NOT_LIVE"]).nullable(),
+  }),
+  orders: z.object({
+    count: z.number().int().min(0).describe("주문 수 (결제 모드를 가리지 않는다)"),
+  }),
+});
+export type StarterStatus = z.infer<typeof starterStatusSchema>;

package/src/schemas/store.ts

@@ -260,6 +260,12 @@ export const updateStoreRequestSchema = z
         "비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. " +
           "장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다",
       ),
+    testOrderReviewsAllowed: z
+      .boolean()
+      .optional()
+      .describe(
+        "테스트 결제(샌드박스) 주문의 리뷰 허용. 기본 false — 돈을 내지 않은 주문으로 구매 인증 리뷰가 쌓이지 않게 막는다",
+      ),
     autoDeliverDays: z
       .number()
       .int()
@@ -326,6 +332,11 @@ export const storeSchema = z.object({
       "스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)",
     ),
   guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
+  testOrderReviewsAllowed: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("테스트 결제(샌드박스) 주문의 리뷰 허용. 서버는 항상 싣는다"),
   autoDeliverDays: z.number().int().describe(autoDeliverDaysDescription),
   autoConfirmDays: z.number().int().describe(autoConfirmDaysDescription),
   refundPolicy: refundPolicySchema.describe(