@sayren/store-sdk 0.21.0 → 0.22.0

package/src/schemas/storefront-hosting.ts

@@ -42,6 +42,16 @@ import { RESERVED_STORE_CODES } from "./store";
  * - 409 `STOREFRONT_BUILD_IN_PROGRESS` — 이 사이트에 끝나지 않은 빌드가 있다(사이트당 하나)
  * - 404 `STOREFRONT_BUILD_NOT_FOUND`
  * - 502 `STOREFRONT_SANDBOX_UNAVAILABLE` — 편집 Sandbox 호출이 실패했다. 잠시 뒤 다시 한다
+ *
+ * 소스 내려받기·올리기(#60, `/v1/storefront/site/source/**`, `sayren` CLI):
+ * - 409 `SOURCE_CHANGED` — 작업 트리가 내려받은 뒤(`expectedBaseRef`) 바뀌었다(콘솔·AI 편집). `error.details.currentRef`
+ * - 409 `EDIT_SESSION_OPEN` — 편집 환경이 열려 있다. `endEditSession: true`로 끄고 진행할 수 있다
+ * - 409 `SOURCE_BLOBS_MISSING` — 올리지 않은 파일 내용이 있다(`error.details.hashes`). `POST source/blobs`로 올리고 다시 한다
+ * - 409 `DEPENDENCY_REJECTED` — 쓸 수 없는 npm 의존성이다(`error.details.rejected: [{ name, version, reason, detail }]`)
+ * - 413 `SOURCE_TOO_MANY_NEW_FILES` — 한 번에 새 내용이 800개를 넘는다(`error.details.max`). 나눠서 바꾼다
+ * - 400 `DEPENDENCY_FILES_MISMATCH` — `packageJson`·`lockfile` 내용이 목록의 해시와 다르거나 빠졌다
+ * - 400 `INVALID_SOURCE_REF` · `BLOB_HASH_MISMATCH` · `INVALID_FILE_PATH`(`.env*`·작업 트리 밖 경로)
+ * - 404 `STOREFRONT_SOURCE_NOT_FOUND` — 그 스냅샷이 없다
  */
 
 // ─── 슬러그 ───────────────────────────────────────────────
@@ -69,6 +79,8 @@ export const RESERVED_STOREFRONT_SLUGS: readonly string[] = [
   "dispatch",
   "control",
   "outbound",
+  // 내 도메인(M3)의 CNAME 대상·fallback origin이다(`sites.{호스팅 도메인}`)
+  "sites",
 ];
 
 /**
@@ -160,6 +172,13 @@ export const storefrontVersionSchema = z.object({
   createdByType: z
     .string()
     .describe("만든 행위자 유형 (`USER`·`AGENT`·`APP`·`TOKEN`·`SYSTEM`). 늘어날 수 있다"),
+  createdVia: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "만든 경로 (`CONSOLE` 콘솔 · `AI` AI 에이전트(MCP) · `CLI` `sayren` CLI · `API` 관리 API · `SYSTEM` 자동). 늘어날 수 있다",
+    ),
   createdAt: z.string().describe("만든 시각 (ISO 8601)"),
 });
 export type StorefrontVersion = z.infer<typeof storefrontVersionSchema>;
@@ -185,7 +204,9 @@ export const storefrontDomainSchema = z.object({
   kind: z.enum(["PLATFORM", "CUSTOM"]).describe("`PLATFORM` 슬러그 주소 · `CUSTOM` 내 도메인"),
   status: z
     .enum(["ACTIVE", "HELD"])
-    .describe("`ACTIVE` 사용 중 · `HELD` 슬러그를 바꿔 보류 중(새 주소로 301)"),
+    .describe(
+      "`ACTIVE` 사용 중 · `HELD` 슬러그를 바꿔 보류 중(새 주소로 301). 연결 중인 내 도메인은 싣지 않는다(`GET /v1/storefront/site/domains`)",
+    ),
   isPrimary: z.boolean().describe("대표 주소인가 (`Store.storefrontUrl`)"),
   holdUntil: z.string().nullable().describe("보류가 끝나는 시각 (ISO 8601). 보류가 아니면 null"),
 });
@@ -359,6 +380,264 @@ export const storefrontPreviewLinkSchema = z.object({
 });
 export type StorefrontPreviewLink = z.infer<typeof storefrontPreviewLinkSchema>;
 
+// ─── 내 도메인 (M3) ───────────────────────────────────────
+//
+// 셀러가 가진 도메인(예: `shop.brand.com`)을 사이트 주소로 연결한다. 흐름은 추가(`PENDING_DNS`) → 셀러가 DNS에 TXT(소유 확인)·
+// CNAME(연결)을 넣음 → 서버가 TXT를 확인하면 도메인을 이 스토어에 잡고 인증서 발급을 시작한다(`PENDING_VALIDATION`) → 인증서가
+// 발급되면 `ACTIVE`다. 확인은 서버가 주기적으로 하고 `verify`는 곧바로 한 번 더 본다. 연결된 도메인은 대표 주소로 지정할 수 있고,
+// 대표가 아닌 주소(기본 주소 포함)는 대표 주소로 301한다.
+//
+// - TXT 소유 확인은 도메인마다 새 값이다. CNAME만으로는 연결하지 않는다 — 연결을 끊은 뒤 CNAME이 남은 도메인을 다른 스토어가
+//   가져가지 못하게 한다.
+// - 소유 확인 전(`PENDING_DNS`)에는 도메인을 잡지 않는다. 같은 도메인을 여러 스토어가 추가해 둘 수 있고, 먼저 TXT 확인을 통과한
+//   스토어가 잡는다. 이미 다른 스토어가 잡은 도메인은 409 `STOREFRONT_DOMAIN_TAKEN`이다.
+// - 해제하면 곧바로 연결을 지운다. 연결된 뒤 DNS가 7일 넘게 이 서비스를 가리키지 않으면 서버가 연결을 해제한다.
+// - 결제 복귀·방문 분석·소셜 로그인 허용 목록은 연결된(`ACTIVE`) 도메인을 자동으로 더한다.
+//
+// 오류 코드:
+// - 403 `STOREFRONT_CUSTOM_DOMAINS_DISABLED` — 플랫폼 스위치가 꺼져 도메인을 추가할 수 없다
+// - 400 `STOREFRONT_DOMAIN_INVALID` — 형식이 틀렸거나 연결할 수 없는 도메인이다(`error.details.reason`)
+// - 404 `STOREFRONT_DOMAIN_NOT_FOUND`
+// - 409 `STOREFRONT_DOMAIN_EXISTS` — 이 스토어에 이미 추가한 도메인이다
+// - 409 `STOREFRONT_DOMAIN_TAKEN` — 다른 스토어가 연결했거나 연결 중인 도메인이다
+// - 409 `STOREFRONT_DOMAIN_LIMIT` — 스토어당 도메인 수 상한(`error.details.limit`)
+// - 409 `STOREFRONT_DOMAIN_NOT_ACTIVE` — 연결되지 않았거나 경고(`failureCode`)가 있는 도메인은 대표 주소로 지정할 수 없다
+// - 429 `TOO_MANY_REQUESTS` — 재확인은 스토어당 분당 20번까지다(`error.details.retryAfterSeconds`)
+// - 400 `STOREFRONT_DOMAIN_NOT_REMOVABLE` — 기본 주소는 해제할 수 없다
+
+/**
+ * 연결할 수 없는 도메인 — 플랫폼이 쓰는 도메인과 그 하위(기본 주소는 슬러그로 바꾼다). 호스팅 도메인은 서버 설정이라
+ * `storefrontCustomHostnameProblem`의 인자로 따로 받는다.
+ */
+export const STOREFRONT_PLATFORM_DOMAINS: readonly string[] = [
+  "sayren.co",
+  "sayren.app",
+  "sayren.shop",
+  "avarlabs.com",
+];
+
+/** 공개 인터넷에서 쓸 수 없는 최상위 도메인(RFC 2606·6761·6762 등) */
+const NON_PUBLIC_TLDS: readonly string[] = [
+  "example",
+  "localhost",
+  "local",
+  "test",
+  "invalid",
+  "onion",
+  "internal",
+  "arpa",
+  "home",
+  "lan",
+  "corp",
+  "intranet",
+  "alt",
+];
+
+/**
+ * 공용 접미사 — 누구나 그 아래 이름을 받는 도메인이라 접미사 자체는 연결할 수 없다. Public Suffix List 전체가 아니라 자주 틀리는
+ * 것만 둔다(여기 없는 접미사도 TXT 소유 확인을 통과할 수 없어 연결되지 않는다 — 이 목록은 추가 단계에서 빨리 알려 주는 안내다).
+ */
+export const STOREFRONT_PUBLIC_SUFFIXES: readonly string[] = [
+  "co.kr",
+  "or.kr",
+  "ne.kr",
+  "go.kr",
+  "ac.kr",
+  "re.kr",
+  "pe.kr",
+  "mil.kr",
+  "hs.kr",
+  "ms.kr",
+  "es.kr",
+  "sc.kr",
+  "kg.kr",
+  "seoul.kr",
+  "busan.kr",
+  "incheon.kr",
+  "daegu.kr",
+  "gwangju.kr",
+  "daejeon.kr",
+  "ulsan.kr",
+  "gyeonggi.kr",
+  "gangwon.kr",
+  "chungbuk.kr",
+  "chungnam.kr",
+  "jeonbuk.kr",
+  "jeonnam.kr",
+  "gyeongbuk.kr",
+  "gyeongnam.kr",
+  "jeju.kr",
+  "co.jp",
+  "ne.jp",
+  "or.jp",
+  "com.cn",
+  "net.cn",
+  "com.tw",
+  "com.hk",
+  "co.uk",
+  "org.uk",
+  "com.au",
+  "net.au",
+  "com.sg",
+  "co.nz",
+  "com.br",
+  "github.io",
+  "gitlab.io",
+  "pages.dev",
+  "workers.dev",
+  "vercel.app",
+  "netlify.app",
+  "herokuapp.com",
+  "web.app",
+  "firebaseapp.com",
+  "blogspot.com",
+  "cloudfront.net",
+  "azurewebsites.net",
+  "myshopify.com",
+  "wixsite.com",
+  "cafe24.com",
+  "imweb.me",
+];
+
+/** 스토어당 연결할 수 있는 도메인 수 기본값 — 요금제(#44) 전의 상한이다. 실제 값은 `GET …/domains`의 `limit` */
+export const STOREFRONT_CUSTOM_DOMAIN_LIMIT_DEFAULT = 2;
+/** DNS를 넣을 때까지 기다리는 기간(일) — 지나면 `FAILED`(`DNS_NOT_CONFIGURED`) */
+export const STOREFRONT_DOMAIN_DNS_WAIT_DAYS = 7;
+/** 연결된 도메인의 DNS가 이 서비스를 가리키지 않아도 연결을 유지하는 기간(일) — 지나면 서버가 해제한다 */
+export const STOREFRONT_DOMAIN_DNS_GRACE_DAYS = 7;
+/** 소유 확인 TXT 레코드의 이름 앞부분 — `_sayren-verify.{도메인}` */
+export const STOREFRONT_DOMAIN_TXT_LABEL = "_sayren-verify";
+
+const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const PUNYCODE_TLD = /^xn--[a-z0-9-]{1,59}$/;
+const ALPHA_TLD = /^[a-z]{2,63}$/;
+
+/**
+ * 도메인 정규화 — 앞뒤 공백·끝 점을 떼고 소문자로 바꾸며 국제화 도메인은 punycode(`xn--`)로 바꾼다. 스킴·경로·포트가 붙은 입력
+ * (`https://www.a.com/`)은 호스트만 남기지 않고 그대로 두어 형식 검사에서 떨어진다(서버는 사용자가 적은 도메인만 받는다).
+ * 변환할 수 없으면 입력을 소문자로만 바꿔 돌려준다(형식 검사가 거부한다).
+ */
+export function normalizeStorefrontHostname(input: string): string {
+  const trimmed = input.trim().replace(/\.+$/, "");
+  if (!trimmed || /[\s/:?#@\\[\]%]/.test(trimmed)) return trimmed.toLowerCase();
+  if (/^[\x21-\x7e]+$/.test(trimmed)) return trimmed.toLowerCase();
+  try {
+    // WHATWG URL이 IDNA(UTS #46)로 punycode를 만든다. 브라우저·Node·Workers가 같은 결과다
+    return new URL(`http://${trimmed}`).hostname.toLowerCase();
+  } catch {
+    return trimmed.toLowerCase();
+  }
+}
+
+export type StorefrontHostnameProblem =
+  | "FORMAT"
+  | "IP_ADDRESS"
+  | "SINGLE_LABEL"
+  | "NON_PUBLIC_TLD"
+  | "PLATFORM_DOMAIN"
+  | "PUBLIC_SUFFIX"
+  | "WILDCARD";
+
+/**
+ * 연결할 수 있는 도메인인가(정규화한 값 기준). 문제가 없으면 null이다. 규칙: 253자 이하, 라벨 2개 이상, 라벨은 소문자·숫자·하이픈
+ * 63자 이하(하이픈으로 시작·끝 불가), 최상위 도메인은 영문자이거나 punycode, IP 주소·와일드카드·공개 인터넷 밖 최상위 도메인·
+ * 플랫폼 도메인과 그 하위·공용 접미사 자체는 안 된다. 제어·디스패치 Worker가 형식 규칙의 복제본을 들고 있다(api
+ * `test/storefront-hosting-parity.spec.ts`가 대조한다).
+ */
+export function storefrontCustomHostnameProblem(
+  hostname: string,
+  hostingDomain = "sayren.co",
+): StorefrontHostnameProblem | null {
+  if (hostname.startsWith("*.")) return "WILDCARD";
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || /^\[?[0-9a-f:.]*:[0-9a-f:.]*\]?$/.test(hostname))
+    return "IP_ADDRESS";
+  if (hostname.length === 0 || hostname.length > 253) return "FORMAT";
+  const labels = hostname.split(".");
+  if (labels.length < 2) return "SINGLE_LABEL";
+  if (!labels.every((label) => LABEL.test(label))) return "FORMAT";
+  const tld = labels[labels.length - 1] ?? "";
+  if (!ALPHA_TLD.test(tld) && !PUNYCODE_TLD.test(tld)) return "FORMAT";
+  if (NON_PUBLIC_TLDS.includes(tld)) return "NON_PUBLIC_TLD";
+  const platform = new Set([...STOREFRONT_PLATFORM_DOMAINS, hostingDomain.toLowerCase()]);
+  for (const domain of platform) {
+    if (hostname === domain || hostname.endsWith(`.${domain}`)) return "PLATFORM_DOMAIN";
+  }
+  if (STOREFRONT_PUBLIC_SUFFIXES.includes(hostname)) return "PUBLIC_SUFFIX";
+  return null;
+}
+
+/** 소유 확인 TXT 레코드의 전체 이름 */
+export function storefrontDomainTxtNameOf(hostname: string): string {
+  return `${STOREFRONT_DOMAIN_TXT_LABEL}.${hostname}`;
+}
+
+export const storefrontCustomDomainStatusSchema = z
+  .enum(["PENDING_DNS", "PENDING_VALIDATION", "ACTIVE", "FAILED"])
+  .describe(
+    "`PENDING_DNS` DNS 설정 대기(소유 확인 전) · `PENDING_VALIDATION` 소유 확인됨, 인증서 발급 중 · `ACTIVE` 연결됨 · `FAILED` 연결 실패(`failureCode`)",
+  );
+export type StorefrontCustomDomainStatus = z.infer<typeof storefrontCustomDomainStatusSchema>;
+
+export const storefrontDnsRecordSchema = z.object({
+  type: z.enum(["CNAME", "TXT"]).describe("레코드 유형"),
+  name: z.string().describe("레코드 이름 (전체 이름, 예: `_sayren-verify.shop.brand.com`)"),
+  value: z.string().describe("레코드 값"),
+  purpose: z.enum(["ROUTING", "OWNERSHIP"]).describe("`ROUTING` 연결 · `OWNERSHIP` 소유 확인"),
+});
+export type StorefrontDnsRecord = z.infer<typeof storefrontDnsRecordSchema>;
+
+export const storefrontSiteDomainSchema = z.object({
+  domainId: z.string(),
+  hostname: z.string().describe("호스트 이름 (punycode, 소문자)"),
+  kind: z
+    .enum(["PLATFORM", "CUSTOM"])
+    .describe("`PLATFORM` 기본 주소(슬러그) · `CUSTOM` 내 도메인"),
+  status: storefrontCustomDomainStatusSchema.describe(
+    "기본 주소는 늘 `ACTIVE`다. 내 도메인은 연결 단계",
+  ),
+  isPrimary: z
+    .boolean()
+    .describe("대표 주소인가 (`Store.storefrontUrl`). 대표가 아닌 주소는 대표로 301한다"),
+  dnsRecords: z.array(storefrontDnsRecordSchema).describe("DNS에 넣을 레코드. 기본 주소는 빈 배열"),
+  certificateStatus: z
+    .enum(["PENDING", "ACTIVE", "FAILED"])
+    .nullable()
+    .describe("인증서 상태. 소유 확인 전·기본 주소는 null"),
+  failureCode: z
+    .string()
+    .nullable()
+    .describe(
+      "실패·경고 코드. `DNS_NOT_CONFIGURED` 기한 안에 TXT를 찾지 못함 · `VALIDATION_TIMEOUT` 인증서 발급 기한 지남 · `CERTIFICATE_FAILED` 인증서 발급 실패 · `DNS_NOT_POINTING` 연결된 뒤 DNS가 이 서비스를 가리키지 않음(기한이 지나면 해제) · `DOMAIN_TAKEN` 다른 스토어가 먼저 소유를 확인함 · `HOSTNAME_BLOCKED` 연결이 막힘 · `HOSTNAME_CONFLICT` 연결 준비 중 충돌(운영 확인). 늘어날 수 있다",
+    ),
+  verifiedAt: z.string().nullable().describe("소유를 확인한 시각 (ISO 8601)"),
+  activatedAt: z.string().nullable().describe("연결된 시각 (ISO 8601)"),
+  checkedAt: z.string().nullable().describe("마지막으로 확인한 시각 (ISO 8601)"),
+  createdAt: z.string(),
+});
+export type StorefrontSiteDomain = z.infer<typeof storefrontSiteDomainSchema>;
+
+/** `GET /v1/storefront/site/domains` — 사이트의 주소 목록(기본 주소 + 내 도메인)과 연결 설정 */
+export const storefrontSiteDomainsSchema = z.object({
+  enabled: z.boolean().describe("내 도메인을 추가할 수 있는가 (플랫폼 스위치)"),
+  limit: z
+    .number()
+    .int()
+    .min(0)
+    .describe("스토어당 내 도메인 수 상한 (해제한 도메인은 세지 않는다)"),
+  target: z.string().describe("CNAME 대상 (예: `sites.sayren.co`)"),
+  domains: z.array(storefrontSiteDomainSchema).describe("대표 주소 먼저, 그다음 추가한 순서"),
+});
+export type StorefrontSiteDomains = z.infer<typeof storefrontSiteDomainsSchema>;
+
+export const addStorefrontDomainRequestSchema = z.object({
+  hostname: z
+    .string()
+    .min(1)
+    .max(300)
+    .describe("연결할 도메인 (예: `shop.brand.com`). 서버가 소문자·punycode로 정규화한다"),
+});
+export type AddStorefrontDomainRequest = z.infer<typeof addStorefrontDomainRequestSchema>;
+
 // ─── 편집 (M2b) ───────────────────────────────────────────
 //
 // 셀러(콘솔)와 에이전트(MCP)가 사이트의 작업 트리를 고치고 버전을 만든다. 작업 트리는 사이트당 하나이고 편집 Sandbox
@@ -776,9 +1055,11 @@ export const STOREFRONT_BUILD_TERMINAL_STATUSES: readonly StorefrontBuildStatus[
 
 /**
  * 빌드 단계 — 이 순서로 돈다. 첫 실패에서 멈추지만 규칙 검증(`VERIFY`)은 실패해도 타입 검사까지 이어서 해 한 번에 알려 준다.
- * `UPLOAD`는 사이트 버전 Worker 업로드다(성공하면 발행할 수 있다). 값은 늘어날 수 있다.
+ * `UPLOAD`는 사이트 버전 Worker 업로드다(성공하면 발행할 수 있다). `DEPENDENCIES`는 빌드 시작 전 의존성 검사(거절 목록·보안 권고)다.
+ * 값은 늘어날 수 있다.
  */
 export const STOREFRONT_BUILD_STAGES = [
+  "DEPENDENCIES",
   "VERIFY",
   "RESTORE",
   "INSTALL",
@@ -789,6 +1070,40 @@ export const STOREFRONT_BUILD_STAGES = [
   "UPLOAD",
 ] as const;
 
+/**
+ * 의존성 검사 결과 한 줄(#61) — 거절(`DEPENDENCY_REJECTED`의 `details.rejected`)·경고(빌드 `dependencies`, 소스 교체 `dependencyWarnings`)가
+ * 같은 모양이다. 대상 패키지와 사유. 셀러가 고칠 수 있게 버전·권고 id·거절 사유를 싣는다.
+ * `reason`: `DENYLISTED`(거절 목록) · `ADVISORY`(보안 권고) · `MALWARE`(악성 코드 권고, 패키지 전체) · `INSTALL_SCRIPT`(루트
+ * package.json의 설치 훅은 거절, 의존성의 설치 스크립트는 경고) · `UNSUPPORTED_SOURCE`(레지스트리 밖 설치 경로) · `BUNDLED_DEPENDENCIES`(묶여
+ * 오는 의존성, 경고) · `INVALID_MANIFEST`(package.json·잠금 파일 형식), 늘어날 수 있다.
+ */
+export const storefrontDependencyFindingSchema = z.object({
+  name: z.string().describe("패키지 이름. 파일 전체의 문제면 `package.json`·`pnpm-lock.yaml`"),
+  version: z.string().nullable().describe("해당 버전. 버전과 무관하면 null"),
+  reason: z.string().describe("사유 코드"),
+  detail: z.string().describe("셀러용 설명"),
+  advisory: z
+    .object({
+      id: z.string(),
+      url: z.string().nullable(),
+      severity: z.string(),
+      title: z.string(),
+    })
+    .nullable()
+    .optional()
+    .describe("보안 권고(사유가 `ADVISORY`·`MALWARE`일 때)"),
+});
+export type StorefrontDependencyFinding = z.infer<typeof storefrontDependencyFindingSchema>;
+
+export const storefrontBuildDependenciesSchema = z.object({
+  checkedPackages: z.number().int().min(0).describe("검사한 설치 트리의 패키지(이름·버전) 수"),
+  rejected: z.array(storefrontDependencyFindingSchema).describe("빌드를 막은 의존성"),
+  warnings: z
+    .array(storefrontDependencyFindingSchema)
+    .describe("빌드는 막지 않는 경고(중간 이하 심각도 권고)"),
+});
+export type StorefrontBuildDependencies = z.infer<typeof storefrontBuildDependenciesSchema>;
+
 export const storefrontBuildSchema = z.object({
   buildId: z.string(),
   versionId: z.string(),
@@ -798,13 +1113,13 @@ export const storefrontBuildSchema = z.object({
     .string()
     .nullable()
     .describe(
-      "실패한 단계 (`VERIFY`·`RESTORE`·`INSTALL`·`TYPECHECK`·`BUILD`·`BUNDLE`·`PACK`·`UPLOAD`, 늘어날 수 있다). 실패가 아니면 null",
+      "실패한 단계 (`DEPENDENCIES`·`VERIFY`·`RESTORE`·`INSTALL`·`TYPECHECK`·`BUILD`·`BUNDLE`·`PACK`·`UPLOAD`, 늘어날 수 있다). 실패가 아니면 null",
     ),
   errorCode: z
     .string()
     .nullable()
     .describe(
-      "실패 코드 (`RULES_VIOLATED`·`INSTALL_FAILED`·`TYPECHECK_FAILED`·`BUILD_FAILED`·`BUNDLE_FAILED`·`ARTIFACT_INVALID`·`UPLOAD_FAILED`·`SOURCE_NOT_FOUND`·`CAPACITY_EXHAUSTED`·`INTERNAL`, 늘어날 수 있다). 실패가 아니면 null",
+      "실패 코드 (`DEPENDENCY_REJECTED`·`DEPENDENCY_CHECK_UNAVAILABLE`·`DEPENDENCIES_CHANGED`·`RULES_VIOLATED`·`INSTALL_FAILED`·`INSTALL_TOO_LARGE`·`TYPECHECK_FAILED`·`BUILD_FAILED`·`BUILD_TIMEOUT`·`BUNDLE_FAILED`·`ARTIFACT_TOO_LARGE`·`ARTIFACT_INVALID`·`UPLOAD_FAILED`·`SOURCE_NOT_FOUND`·`CAPACITY_EXHAUSTED`·`INTERNAL`, 늘어날 수 있다). 실패가 아니면 null",
     ),
   logTail: z.string().nullable().describe("실패 단계 출력 꼬리 (최대 8KB). 없으면 null"),
   stages: z
@@ -819,6 +1134,13 @@ export const storefrontBuildSchema = z.object({
   verify: storefrontVerifyReportSchema
     .nullable()
     .describe("규칙 검증 보고서(위반 상세는 50건까지). 그 단계까지 가지 못했으면 null"),
+  // 옛 api 응답에는 없다 — 새 SDK가 배포 전 api와 함께 쓰여도 깨지지 않게 선택 필드다
+  dependencies: storefrontBuildDependenciesSchema
+    .nullable()
+    .optional()
+    .describe(
+      "의존성 검사 결과(거절 목록·보안 권고). 빌드 시작 전에 돈다. 거절이 있으면 `failureStage: DEPENDENCIES`, `errorCode: DEPENDENCY_REJECTED`다. 아직 검사 전이면 null(옛 서버는 싣지 않는다)",
+    ),
   queuedAt: z.string(),
   startedAt: z.string().nullable(),
   finishedAt: z.string().nullable(),
@@ -836,6 +1158,13 @@ export const storefrontBuildListQuerySchema = z.object({
  */
 export const createStorefrontVersionRequestSchema = z.object({
   message: z.string().max(200).optional().describe("버전 메모 (에이전트는 바꾼 내용 요약)"),
+  expectedSourceRef: z
+    .string()
+    .max(200)
+    .optional()
+    .describe(
+      "고정할 작업 트리 (`PUT /v1/storefront/site/source`의 `sourceRef`). 주면 지금 작업 트리가 이 값일 때만 버전을 만든다(다르면 409 `SOURCE_CHANGED`)",
+    ),
 });
 export type CreateStorefrontVersionRequest = z.infer<typeof createStorefrontVersionRequestSchema>;
 
@@ -854,3 +1183,142 @@ export type StorefrontVersionCreated = z.infer<typeof storefrontVersionCreatedSc
 export const createStorefrontEditPreviewLinkRequestSchema =
   createStorefrontPreviewLinkRequestSchema;
 export type CreateStorefrontEditPreviewLinkRequest = CreateStorefrontPreviewLinkRequest;
+
+// ─── 소스 내려받기·올리기 (#60, `sayren` CLI) ─────────────────────────────
+//
+// 셀러가 사이트 작업 트리를 로컬로 받아(`npx sayren pull`) 고치고 되돌려 놓는다(`npx sayren deploy`). 콘솔·AI 편집과 같은
+// 작업 트리다. 올리는 것은 소스뿐이고 빌드는 서버가 한다(버전 만들기). 흐름:
+// 1. `GET source` — 지금 작업 트리를 고정하고(`sourceRef`) 압축 파일 크기를 알린다
+// 2. `GET source/archive?sourceRef=&part=` — 압축 파일(tar.gz)을 4MiB씩 받는다
+// 3. `PUT source` — 바꾼 뒤 트리 전체 목록(경로·해시·크기)과 `package.json`·`pnpm-lock.yaml` 내용을 보낸다(의존성 판정). 서버에 없는 내용은 409 `SOURCE_BLOBS_MISSING`이
+//    알려 주고, `POST source/blobs`로 올린 뒤 다시 보낸다. `expectedBaseRef`(내려받은 `sourceRef`)가 지금과 다르면 409 `SOURCE_CHANGED`
+
+/** 압축 파일 조각 하나의 최대 크기(바이트) */
+export const STOREFRONT_SOURCE_PART_BYTES = 4 * 1024 * 1024;
+/** 내용 올리기 한 번의 최대 파일 수 */
+export const STOREFRONT_SOURCE_BLOB_BATCH_MAX = 200;
+/** 작업 트리 파일 수 상한 */
+export const STOREFRONT_WORKSPACE_MAX_FILES = 2000;
+
+/** 작업 트리 스냅샷 키 — `sources/{siteId}/{sha256}.tgz` */
+export const storefrontSourceRefSchema = z
+  .string()
+  .regex(/^sources\/sfs_[a-z0-9]{8,40}\/[0-9a-f]{64}\.tgz$/, "작업 트리 스냅샷 키 형식이 아닙니다")
+  .describe("작업 트리 스냅샷 (`sources/{siteId}/{sha256}.tgz`, 내용 주소)");
+
+/** `GET /v1/storefront/site/source` — 지금 작업 트리(편집 환경이 떠 있으면 지금 내용을 고정한다) */
+export const storefrontSourceSchema = z.object({
+  siteId: z.string(),
+  storeId: z.string(),
+  storeCode: z.string().describe("스토어 코드 — 로컬 개발 서버의 `SAYREN_STORE_CODE`"),
+  sourceRef: storefrontSourceRefSchema,
+  treeSha256: z.string().describe("트리 지문 (경로 오름차순 `{path}\\t{sha256}\\n`의 SHA-256)"),
+  files: z.number().int().min(0).describe("파일 수"),
+  bytes: z.number().int().min(0).describe("파일 크기 합"),
+  archive: z.object({
+    format: z.literal("tar+gzip"),
+    bytes: z.number().int().min(0).describe("압축 파일 크기"),
+    sha256: z.string().describe("압축 파일의 SHA-256 (`sourceRef`의 해시와 같다)"),
+    parts: z.number().int().min(0).describe("`GET source/archive`로 받을 조각 수"),
+    partBytes: z.number().int().describe("조각 하나의 최대 크기"),
+  }),
+  editSessionOpen: z
+    .boolean()
+    .describe("편집 환경이 열려 있는가 (올리기 전에 끄거나 `endEditSession`)"),
+});
+export type StorefrontSource = z.infer<typeof storefrontSourceSchema>;
+
+export const storefrontSourceArchiveQuerySchema = z.object({
+  sourceRef: storefrontSourceRefSchema,
+  part: z.coerce.number().int().min(0).max(100).optional().describe("조각 번호 (0부터, 기본 0)"),
+});
+
+/** `GET /v1/storefront/site/source/archive` — 압축 파일 조각 */
+export const storefrontSourceArchivePartSchema = z.object({
+  sourceRef: storefrontSourceRefSchema,
+  part: z.number().int().min(0),
+  parts: z.number().int().min(0),
+  offset: z.number().int().min(0),
+  bytes: z.number().int().min(0).describe("이 조각의 크기"),
+  totalBytes: z.number().int().min(0),
+  content: z.string().describe("조각 내용 (base64)"),
+});
+export type StorefrontSourceArchivePart = z.infer<typeof storefrontSourceArchivePartSchema>;
+
+/** `POST /v1/storefront/site/source/blobs` — 파일 내용 올리기(해시 키, 다시 올려도 안전하다). 작업 트리는 바뀌지 않는다 */
+export const uploadStorefrontSourceBlobsRequestSchema = z.object({
+  blobs: z
+    .array(
+      z.object({
+        hash: storefrontFileHashSchema,
+        content: z.string().describe("파일 내용 (base64, 1MiB까지)"),
+      }),
+    )
+    .min(1)
+    .max(STOREFRONT_SOURCE_BLOB_BATCH_MAX),
+});
+export type UploadStorefrontSourceBlobsRequest = z.infer<
+  typeof uploadStorefrontSourceBlobsRequestSchema
+>;
+
+export const storefrontSourceBlobsResultSchema = z.object({
+  stored: z.number().int().min(0).describe("새로 올린 수"),
+  existing: z.number().int().min(0).describe("이미 있던 수"),
+});
+export type StorefrontSourceBlobsResult = z.infer<typeof storefrontSourceBlobsResultSchema>;
+
+/**
+ * `PUT /v1/storefront/site/source` — 작업 트리 전체를 이 목록으로 바꾼다(없는 경로는 지운다). 전부 아니면 전무다.
+ * `package.json`·`pnpm-lock.yaml`도 바꿀 수 있고 의존성은 허용 목록 안이어야 한다. `.env*`·작업 트리 밖 경로는 받지 않는다.
+ */
+export const replaceStorefrontSourceRequestSchema = z.object({
+  expectedBaseRef: storefrontSourceRefSchema
+    .optional()
+    .describe(
+      "내려받은 작업 트리. 지금 작업 트리가 이 값일 때만 바꾼다. 생략하면 조건 없이 덮어쓴다",
+    ),
+  files: z
+    .array(
+      z.object({
+        path: storefrontFilePathSchema,
+        hash: storefrontFileHashSchema,
+        size: z.number().int().min(0).max(STOREFRONT_FILE_MAX_BYTES),
+      }),
+    )
+    .min(1)
+    .max(STOREFRONT_WORKSPACE_MAX_FILES)
+    .refine((files) => new Set(files.map((file) => file.path)).size === files.length, {
+      message: "같은 경로를 두 번 실을 수 없습니다",
+    }),
+  endEditSession: z
+    .boolean()
+    .optional()
+    .describe("열린 편집 환경을 끄고 진행한다 (기본 false — 열려 있으면 409 `EDIT_SESSION_OPEN`)"),
+  packageJson: z
+    .string()
+    .max(STOREFRONT_FILE_MAX_BYTES)
+    .optional()
+    .describe(
+      "`files`에 `package.json`이 있으면 그 내용(utf8). 서버가 의존성을 판정한다. 해시가 목록과 다르면 400 `DEPENDENCY_FILES_MISMATCH`",
+    ),
+  lockfile: z
+    .string()
+    .max(STOREFRONT_FILE_MAX_BYTES)
+    .optional()
+    .describe("`files`에 `pnpm-lock.yaml`이 있으면 그 내용(utf8)"),
+});
+export type ReplaceStorefrontSourceRequest = z.infer<typeof replaceStorefrontSourceRequestSchema>;
+
+export const storefrontSourceReplacedSchema = z.object({
+  sourceRef: storefrontSourceRefSchema.describe("새 작업 트리 — 다음 올리기의 `expectedBaseRef`"),
+  previousRef: z.string().describe("바꾸기 전 작업 트리"),
+  treeSha256: z.string(),
+  files: z.number().int().min(0),
+  bytes: z.number().int().min(0),
+  changed: z.boolean().describe("내용이 바뀌었는가 (같은 트리를 다시 올리면 false)"),
+  endedEditSession: z.boolean().describe("열린 편집 환경을 끄고 진행했는가"),
+  dependencyWarnings: z
+    .array(storefrontDependencyFindingSchema)
+    .describe("배포를 막지 않는 의존성 경고 (보안 권고 등)"),
+});
+export type StorefrontSourceReplaced = z.infer<typeof storefrontSourceReplacedSchema>;