@sayren/store-sdk 0.35.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -87,11 +87,14 @@ import {
 import {
   type CollectionCreateRequestInput,
   type CollectionListParams,
+  type CollectionLocalizationRequest,
   type CollectionPatchRequest,
   type CollectionPreviewRequest,
   type CollectionProductsAddRequest,
   type CollectionProductsReplaceRequest,
   collectionCreateRequestSchema,
+  collectionLocalizationRequestSchema,
+  collectionLocalizationSchema,
   collectionPageSchema,
   collectionPatchRequestSchema,
   collectionPreviewRequestSchema,
@@ -277,6 +280,7 @@ import {
   type VerifyPaymentProviderRequest,
   verifyPaymentProviderRequestSchema,
 } from "./schemas/payment";
+import { publicPlansSchema } from "./schemas/plans";
 import {
   customerPointsSchema,
   type PointAdjustmentRequest,
@@ -311,8 +315,11 @@ import {
   variantStockSchema,
 } from "./schemas/product";
 import {
+  type InfoSectionLocalizationRequest,
   type InfoSectionRequestInput,
   infoSchemaSchema,
+  infoSectionLocalizationRequestSchema,
+  infoSectionLocalizationSchema,
   infoSectionRequestSchema,
   infoSectionSchema,
   platformCodeSchema,
@@ -325,9 +332,12 @@ import {
 import {
   type SavedOptionSetFromProductRequestInput,
   type SavedOptionSetListParams,
+  type SavedOptionSetLocalizationRequest,
   type SavedOptionSetRequestInput,
   savedOptionSetFromProductRequestSchema,
   savedOptionSetFromProductResultSchema,
+  savedOptionSetLocalizationRequestSchema,
+  savedOptionSetLocalizationSchema,
   savedOptionSetRequestSchema,
   savedOptionSetSchema,
 } from "./schemas/saved-option-set";
@@ -360,12 +370,14 @@ import {
   addStorefrontDomainRequestSchema,
   type ChangeStorefrontSlugRequest,
   type ChangeStorefrontTemplateRequest,
+  type ConnectStorefrontGitRequest,
   type CreateStorefrontEditPreviewLinkRequest,
   type CreateStorefrontPreviewLinkRequest,
   type CreateStorefrontSiteRequest,
   type CreateStorefrontVersionRequest,
   changeStorefrontSlugRequestSchema,
   changeStorefrontTemplateRequestSchema,
+  connectStorefrontGitRequestSchema,
   createStorefrontEditPreviewLinkRequestSchema,
   createStorefrontPreviewLinkRequestSchema,
   createStorefrontSiteRequestSchema,
@@ -374,6 +386,8 @@ import {
   type DisableStorefrontHostingRequest,
   deleteStorefrontFileRequestSchema,
   disableStorefrontHostingRequestSchema,
+  type LinkStorefrontGitInstallationRequest,
+  linkStorefrontGitInstallationRequestSchema,
   type MoveStorefrontFileRequest,
   moveStorefrontFileRequestSchema,
   type PublishStorefrontVersionRequest,
@@ -385,8 +399,10 @@ import {
   rollbackStorefrontRequestSchema,
   runStorefrontCheckRequestSchema,
   type SearchStorefrontFilesRequest,
+  type SetStorefrontDeployApprovalRequest,
   type SetStorefrontVisibilityRequest,
   searchStorefrontFilesRequestSchema,
+  setStorefrontDeployApprovalRequestSchema,
   setStorefrontVisibilityRequestSchema,
   storefrontBuildSchema,
   storefrontCheckSchema,
@@ -398,6 +414,9 @@ import {
   storefrontFileMoveResultSchema,
   storefrontFileSearchResultSchema,
   storefrontFileWriteResultSchema,
+  storefrontGitConnectStateSchema,
+  storefrontGitRepositorySchema,
+  storefrontGitStatusSchema,
   storefrontHostingSchema,
   storefrontPreviewLinkSchema,
   storefrontSiteDomainSchema,
@@ -421,7 +440,7 @@ import {
   type WriteStorefrontFilesRequest,
   writeStorefrontFilesRequestSchema,
 } from "./schemas/storefront-hosting";
-import { publicPlansSchema, storeSubscriptionSchema } from "./schemas/subscription";
+import { storeSubscriptionSchema } from "./schemas/subscription";
 import {
   type UploadPurpose,
   type UploadRequest,
@@ -701,6 +720,27 @@ export function createStoreClient(options: StoreClientOptions) {
           savedOptionSetFromProductResultSchema,
           { body: savedOptionSetFromProductRequestSchema.parse(body) },
         ),
+      /** 번역(이슈 #134) — 기본 언어 이름이 키다. 불러올 때 상품 번역으로 복사한다 */
+      localizations: {
+        list: (optionSetId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/saved-option-sets/${optionSetId}/localizations`,
+            z.array(savedOptionSetLocalizationSchema),
+          ),
+        put: (optionSetId: string, locale: string, body: SavedOptionSetLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/saved-option-sets/${optionSetId}/localizations/${locale}`,
+            savedOptionSetLocalizationSchema,
+            { body: savedOptionSetLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (optionSetId: string, locale: string) =>
+          storeHttp.requestVoid(
+            "DELETE",
+            path`/saved-option-sets/${optionSetId}/localizations/${locale}`,
+          ),
+      },
     },
 
     /**
@@ -737,6 +777,27 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       remove: (infoSectionId: string) =>
         storeHttp.requestVoid("DELETE", path`/info-sections/${infoSectionId}`),
+      /** 번역(이슈 #134) — 언어별 제목·본문 */
+      localizations: {
+        list: (infoSectionId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/info-sections/${infoSectionId}/localizations`,
+            z.array(infoSectionLocalizationSchema),
+          ),
+        put: (infoSectionId: string, locale: string, body: InfoSectionLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/info-sections/${infoSectionId}/localizations/${locale}`,
+            infoSectionLocalizationSchema,
+            { body: infoSectionLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (infoSectionId: string, locale: string) =>
+          storeHttp.requestVoid(
+            "DELETE",
+            path`/info-sections/${infoSectionId}/localizations/${locale}`,
+          ),
+      },
     },
 
     /**
@@ -786,6 +847,27 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("POST", "/collections/preview", collectionPreviewSchema, {
           body: collectionPreviewRequestSchema.parse(body),
         }),
+      /** 번역(이슈 #134) — 언어별 제목·설명·SEO */
+      localizations: {
+        list: (collectionId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/collections/${collectionId}/localizations`,
+            z.array(collectionLocalizationSchema),
+          ),
+        put: (collectionId: string, locale: string, body: CollectionLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/collections/${collectionId}/localizations/${locale}`,
+            collectionLocalizationSchema,
+            { body: collectionLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (collectionId: string, locale: string) =>
+          storeHttp.requestVoid(
+            "DELETE",
+            path`/collections/${collectionId}/localizations/${locale}`,
+          ),
+      },
     },
 
     categories: {
@@ -2255,6 +2337,43 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("PUT", "/storefront/site/source", storefrontSourceReplacedSchema, {
           body: replaceStorefrontSourceRequestSchema.parse(body),
         }),
+      /** `PUT /v1/storefront/site/deploy-approval` — 승인 없이 배포(상점 플랫폼 OWNER·ADMIN 전용) */
+      setDeployApproval: (body: SetStorefrontDeployApprovalRequest) =>
+        storeHttp.request("PUT", "/storefront/site/deploy-approval", storefrontSiteSchema, {
+          body: setStorefrontDeployApprovalRequestSchema.parse(body),
+        }),
+      /** `GET /v1/storefront/site/git` — Git 원천(발행 소스를 둔 저장소)과 상태(#138) */
+      getGit: () => storeHttp.request("GET", "/storefront/site/git", storefrontGitStatusSchema),
+      /** `POST /v1/storefront/site/git/installations/state` — GitHub 설치 화면에 싣는 1회용 state(상점 플랫폼 전용) */
+      createGitConnectState: () =>
+        storeHttp.request(
+          "POST",
+          "/storefront/site/git/installations/state",
+          storefrontGitConnectStateSchema,
+        ),
+      /** `POST /v1/storefront/site/git/installations` — GitHub App 설치 확인(상점 플랫폼 전용) → 그 설치의 저장소 */
+      linkGitInstallation: (body: LinkStorefrontGitInstallationRequest) =>
+        storeHttp.request(
+          "POST",
+          "/storefront/site/git/installations",
+          z.array(storefrontGitRepositorySchema),
+          { body: linkStorefrontGitInstallationRequestSchema.parse(body) },
+        ),
+      /** `GET /v1/storefront/site/git/installations/{installationId}/repositories` — 확인한 설치의 저장소(상점 플랫폼 전용) */
+      listGitRepositories: (installationId: number) =>
+        storeHttp.request(
+          "GET",
+          `/storefront/site/git/installations/${encodeURIComponent(String(installationId))}/repositories`,
+          z.array(storefrontGitRepositorySchema),
+        ),
+      /** `POST /v1/storefront/site/git/connect` — 셀러 GitHub 저장소 연결(상점 플랫폼 전용) */
+      connectGit: (body: ConnectStorefrontGitRequest) =>
+        storeHttp.request("POST", "/storefront/site/git/connect", storefrontGitStatusSchema, {
+          body: connectStorefrontGitRequestSchema.parse(body),
+        }),
+      /** `POST /v1/storefront/site/git/disconnect` — 연결 해제(sayren 저장소로 되돌림, 상점 플랫폼 전용) */
+      disconnectGit: () =>
+        storeHttp.request("POST", "/storefront/site/git/disconnect", storefrontGitStatusSchema),
     },
 
     subscription: {

package/src/index.ts

@@ -42,6 +42,7 @@ export * from "./schemas/market";
 export * from "./schemas/misc";
 export * from "./schemas/order";
 export * from "./schemas/payment";
+export * from "./schemas/plans";
 export * from "./schemas/points";
 export * from "./schemas/product";
 export * from "./schemas/product-info";

package/src/schemas/collection.ts

@@ -587,3 +587,28 @@ export const collectionPreviewSchema = z.object({
 });
 
 export type CollectionPreview = z.infer<typeof collectionPreviewSchema>;
+
+/**
+ * 컬렉션 번역 (이슈 #134) — 언어 하나의 제목·설명·SEO. 컬렉션 필드는 상점 기본 언어 값이고 번역 레코드가 언어별 값이다.
+ * 비운 칸(null)은 스토어프론트가 기본 언어 값으로 대체한다(칸 단위 대체).
+ */
+export const collectionLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  title: z.string().nullable().describe("제목. null이면 기본 언어 제목"),
+  description: z.string().nullable(),
+  metaTitle: z.string().nullable(),
+  metaDescription: z.string().nullable(),
+  updatedAt: z.string(),
+});
+
+export type CollectionLocalization = z.infer<typeof collectionLocalizationSchema>;
+
+/** `PUT /v1/collections/{collectionId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 빠진 칸은 null(기본 언어 값으로 대체)이다 */
+export const collectionLocalizationRequestSchema = z.strictObject({
+  title: z.string().trim().min(1).max(MAX_COLLECTION_TITLE).nullable().optional(),
+  description: z.string().trim().max(MAX_COLLECTION_DESCRIPTION).nullable().optional(),
+  metaTitle: z.string().trim().max(60).nullable().optional(),
+  metaDescription: z.string().trim().max(160).nullable().optional(),
+});
+
+export type CollectionLocalizationRequest = z.infer<typeof collectionLocalizationRequestSchema>;

package/src/schemas/plans.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { responsePlanCodeSchema } from "./subscription";
+
+/**
+ * 요금제 비교표 — `GET /v1/public/plans`(인증 없음). 요금제마다 가격과 기능 키 값을 준다. 값은 서버가 관리하고(사내 어드민 게시) 언제든
+ * 바뀔 수 있으니 코드에 요금제 수치를 두지 않는다. 상점 하나의 구독·사용량은 `subscription.ts`다
+ */
+
+const limitOrContract = (description: string) =>
+  z.number().int().nullable().describe(`${description}. null이면 계약(엔터프라이즈)·한도 없음`);
+
+/**
+ * 요금제 기능 키 값 — 요금제 비교표·상점 플랫폼 요금제 화면이 쓴다. 키는 서버 판정의 기능 키와 같다(추가만 한다). 상위 요금제는 하위 요금제
+ * 기능을 모두 포함한다
+ */
+export const planEntitlementsSchema = z
+  .object({
+    "features.members": z
+      .boolean()
+      .describe("소유자 외 구성원(관리자·직원)의 초대와 상점 접근. false면 소유자만 쓴다"),
+    "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.public_apps": limitOrContract("공개 앱(앱 스토어 게시 앱) 설치 수"),
+    "limits.private_apps": limitOrContract(
+      "비공개 앱(이 상점 전용 앱) 설치 수(0이면 설치할 수 없다)",
+    ),
+    "limits.ai_credits_monthly": limitOrContract(
+      "AI 상점 도우미 월 크레딧(1 크레딧 = 모델 원가 $0.01, 이월 없음)",
+    ),
+    "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/schemas/product-info.ts

@@ -188,3 +188,29 @@ export const infoSectionRequestSchema = z.object({
 
 export type InfoSectionRequest = z.infer<typeof infoSectionRequestSchema>;
 export type InfoSectionRequestInput = z.input<typeof infoSectionRequestSchema>;
+
+/**
+ * 안내 섹션 번역 (이슈 #134) — 언어 하나의 제목·본문. 섹션 필드는 상점 기본 언어 값이다. 비운 칸(null)은 스토어프론트가 기본 언어 값으로 대체한다.
+ * 섹션을 연결한 모든 상품이 같은 번역을 보인다.
+ */
+export const infoSectionLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  title: z.string().nullable(),
+  body: z
+    .string()
+    .nullable()
+    .describe("본문 HTML(상세설명과 같은 정화 규칙). null이면 기본 언어 본문"),
+  bodyJson: z.string().nullable(),
+  updatedAt: z.string(),
+});
+
+export type InfoSectionLocalization = z.infer<typeof infoSectionLocalizationSchema>;
+
+/** `PUT /v1/info-sections/{infoSectionId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 빠진 칸은 null이다 */
+export const infoSectionLocalizationRequestSchema = z.strictObject({
+  title: z.string().trim().min(1).max(MAX_INFO_SECTION_TITLE).nullable().optional(),
+  body: z.string().nullable().optional(),
+  bodyJson: z.string().nullable().optional(),
+});
+
+export type InfoSectionLocalizationRequest = z.infer<typeof infoSectionLocalizationRequestSchema>;

package/src/schemas/product-localization.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { MAX_PRODUCT_IMAGES, productImageUrlSchema } from "./product";
+import { MAX_NOTICE_VALUE_LENGTH } from "./product-info";
 
 /**
  * 상품 번역 (이슈 #134) — 언어 하나의 상품명·상세설명·이미지·옵션 이름. 상품 필드는 상점 기본 언어 값이고 번역 레코드가 언어별 값이다.
@@ -24,8 +25,14 @@ const translatedCustomInputSchema = z.object({
   placeholder: z.string().nullable().describe("입력 안내. null이면 기본 언어 안내"),
 });
 
+const translatedNoticeValueSchema = z.object({
+  key: z.string().describe("고시 칸 키"),
+  label: z.string().describe("칸 이름(원문)"),
+  value: z.string().nullable().describe("셀러 값 번역. null이면 기본 언어 값"),
+});
+
 /**
- * 조회 응답 — 지금 상품의 옵션명·값·직접 입력 항목을 모두 싣고 번역하지 않은 칸은 null이다.
+ * 조회 응답 — 지금 상품의 옵션명·값·직접 입력 항목, 셀러가 적은 고시 칸을 모두 싣고 번역하지 않은 칸은 null이다.
  * `optionGroups`는 조합 옵션, `addonGroups`는 추가 선택이다(상품 응답과 같은 구분)
  */
 export const productLocalizationSchema = z.object({
@@ -37,6 +44,13 @@ export const productLocalizationSchema = z.object({
   optionGroups: z.array(translatedOptionGroupSchema),
   addonGroups: z.array(translatedOptionGroupSchema),
   customInputs: z.array(translatedCustomInputSchema),
+  notice: z
+    .array(translatedNoticeValueSchema)
+    .optional()
+    .default([])
+    .describe(
+      "셀러가 적은 상품정보제공 고시 칸의 값 번역(이슈 #134). 출처·법정 문구 칸은 싣지 않는다",
+    ),
   updatedAt: z.string(),
 });
 
@@ -71,6 +85,37 @@ export const productLocalizationRequestSchema = z.strictObject({
       }),
     )
     .optional(),
+  notice: z
+    .array(
+      z.strictObject({
+        key: z.string(),
+        value: z.string().trim().min(1).max(MAX_NOTICE_VALUE_LENGTH).nullable().optional(),
+      }),
+    )
+    .optional()
+    .describe(
+      "고시 칸 값 번역. 상품에 셀러 값이 없는 칸 키는 400 `PRODUCT_LOCALIZATION_TARGET_NOT_FOUND`",
+    ),
 });
 
 export type ProductLocalizationRequest = z.infer<typeof productLocalizationRequestSchema>;
+
+/**
+ * 번역할 칸이 비었는가(이슈 #134, 2026-10-18 결정: 완성도 대신 「번역 필요」 표시만) — 상품명, 기본 언어에 본문이 있는 상세설명,
+ * 옵션명·값·직접 입력 항목명, 셀러가 적은 고시 칸. 이미지·입력 안내는 기본 언어 값을 그대로 써도 되는 칸이라 세지 않는다.
+ * 상점 플랫폼(상품 수정·목록)과 관리 목록 응답이 같은 함수다
+ */
+export function productLocalizationNeedsTranslation(
+  localization: Pick<
+    ProductLocalization,
+    "name" | "description" | "optionGroups" | "addonGroups" | "customInputs"
+  > & { notice?: ProductLocalization["notice"] },
+  base: { description?: string | null },
+): boolean {
+  if (!localization.name) return true;
+  if ((base.description ?? "").trim() && !localization.description) return true;
+  const groups = [...localization.optionGroups, ...localization.addonGroups];
+  if (groups.some((group) => !group.name || group.values.some((value) => !value.name))) return true;
+  if (localization.customInputs.some((item) => !item.label)) return true;
+  return (localization.notice ?? []).some((entry) => !entry.value);
+}

package/src/schemas/product.ts

@@ -67,6 +67,18 @@ export const productSummarySchema = z.object({
     .describe(
       "상점을 만들 때 넣은 샘플 상품인가(이슈 #70). 상점 플랫폼이 「샘플」 배지를 단다. 스토어프론트에는 싣지 않는다. 서버는 항상 싣는다",
     ),
+  localizations: z
+    .array(
+      z.object({
+        locale: z.string().describe("언어(BCP 47)"),
+        needsTranslation: z
+          .boolean()
+          .describe("번역할 칸이 비었는가(`productLocalizationNeedsTranslation`과 같은 규칙)"),
+      }),
+    )
+    .optional()
+    .default([])
+    .describe("번역 레코드가 있는 언어(이슈 #134). 상점 기본 언어는 싣지 않는다"),
 });
 
 export type ProductSummary = z.infer<typeof productSummarySchema>;
@@ -372,7 +384,7 @@ export const discountSchema = z.object({
 
 export type Discount = z.infer<typeof discountSchema>;
 
-export const productSchema = productSummarySchema.extend({
+export const productSchema = productSummarySchema.omit({ localizations: true }).extend({
   prices: z
     .array(storedProductCurrencyPriceSchema)
     .optional()

package/src/schemas/saved-option-set.ts

@@ -174,3 +174,65 @@ export const savedOptionSetListQuerySchema = z.object({
   sort: savedOptionSetSortSchema.optional().describe("정렬 (기본 updatedAt.desc)"),
   ...pageQueryShape({ defaultSize: 20, maxSize: 200 }),
 });
+
+/**
+ * 저장 옵션 번역 (이슈 #134) — 저장 옵션에는 id가 없어 **기본 언어 이름이 키**다(`baseName`·`baseLabel`).
+ * 상품이 불러올 때 상품 번역으로 함께 복사하고(상품 저장 트랜잭션), 그 뒤로는 상품 번역이 원천이다 — 저장 옵션 번역을 고쳐도
+ * 이미 불러온 상품은 그대로다. 기본 언어 이름을 바꾸면 그 이름의 번역은 읽지 않는다.
+ */
+export const savedOptionSetLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  groups: z.array(
+    z.object({
+      baseName: z.string().describe("기본 언어 옵션명"),
+      name: z.string().nullable().describe("번역 옵션명. null이면 기본 언어 이름"),
+      values: z.array(
+        z.object({
+          baseName: z.string(),
+          name: z.string().nullable(),
+        }),
+      ),
+    }),
+  ),
+  customInputs: z.array(
+    z.object({
+      baseLabel: z.string().describe("기본 언어 항목명"),
+      label: z.string().nullable(),
+      placeholder: z.string().nullable(),
+    }),
+  ),
+  updatedAt: z.string(),
+});
+
+export type SavedOptionSetLocalization = z.infer<typeof savedOptionSetLocalizationSchema>;
+
+/**
+ * `PUT /v1/saved-option-sets/{optionSetId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 번역할 이름만 보낸다.
+ * 저장 옵션에 없는 기본 언어 이름은 400 `OPTION_SET_LOCALIZATION_TARGET_NOT_FOUND`, 번역 이름 중복은 상품과 같은 규칙으로 400 `INVALID_OPTION_MODEL`이다
+ */
+export const savedOptionSetLocalizationRequestSchema = z.strictObject({
+  groups: z
+    .array(
+      z.strictObject({
+        baseName: z.string(),
+        name: nameSchema.nullable().optional(),
+        values: z
+          .array(z.strictObject({ baseName: z.string(), name: nameSchema.nullable().optional() }))
+          .optional(),
+      }),
+    )
+    .optional(),
+  customInputs: z
+    .array(
+      z.strictObject({
+        baseLabel: z.string(),
+        label: z.string().trim().min(1).max(30).nullable().optional(),
+        placeholder: z.string().trim().min(1).max(100).nullable().optional(),
+      }),
+    )
+    .optional(),
+});
+
+export type SavedOptionSetLocalizationRequest = z.infer<
+  typeof savedOptionSetLocalizationRequestSchema
+>;