@sayren/store-sdk 0.33.0 → 0.35.0

package/package.json

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

package/src/client.ts

@@ -63,9 +63,12 @@ import { myAccountSchema, myStoreSchema } from "./schemas/auth";
 import {
   type CategoryCreateRequest,
   type CategoryDeleteStrategy,
+  type CategoryLocalizationRequest,
   type CategoryPatchRequest,
   categoryAttributeSchema,
   categoryCreateRequestSchema,
+  categoryLocalizationRequestSchema,
+  categoryLocalizationSchema,
   categoryPatchRequestSchema,
   categorySchema,
   categorySearchResultSchema,
@@ -307,6 +310,18 @@ import {
   variantStockRequestSchema,
   variantStockSchema,
 } from "./schemas/product";
+import {
+  type InfoSectionRequestInput,
+  infoSchemaSchema,
+  infoSectionRequestSchema,
+  infoSectionSchema,
+  platformCodeSchema,
+} from "./schemas/product-info";
+import {
+  type ProductLocalizationRequest,
+  productLocalizationRequestSchema,
+  productLocalizationSchema,
+} from "./schemas/product-localization";
 import {
   type SavedOptionSetFromProductRequestInput,
   type SavedOptionSetListParams,
@@ -585,6 +600,24 @@ export function createStoreClient(options: StoreClientOptions) {
           body: productPatchRequestSchema.parse(body),
         }),
       remove: (productId: string) => storeHttp.requestVoid("DELETE", path`/products/${productId}`),
+      /** 번역(이슈 #134) — 언어별 상품명·상세설명·이미지·옵션 이름 */
+      localizations: {
+        list: (productId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/products/${productId}/localizations`,
+            z.array(productLocalizationSchema),
+          ),
+        put: (productId: string, locale: string, body: ProductLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/products/${productId}/localizations/${locale}`,
+            productLocalizationSchema,
+            { body: productLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (productId: string, locale: string) =>
+          storeHttp.requestVoid("DELETE", path`/products/${productId}/localizations/${locale}`),
+      },
       bulkUpdateStatus: (productIds: string[], status: ProductStatus, idempotencyKey?: string) =>
         storeHttp.request("POST", "/products/bulk/status", bulkResultSchema, {
           body: { productIds, status: productStatusSchema.parse(status) },
@@ -670,6 +703,42 @@ export function createStoreClient(options: StoreClientOptions) {
         ),
     },
 
+    /**
+     * 상품정보제공 고시 품목군(이슈 #135) — 플랫폼 코드 표. 현재 버전만 싣는다. 권한은 상품 조회(`product:r`)다
+     */
+    infoSchemas: {
+      list: (params?: { kind?: string }) =>
+        storeHttp.request("GET", "/info-schemas", z.array(infoSchemaSchema), {
+          query: params as Query,
+        }),
+    },
+
+    /** 플랫폼 코드 묶음(이슈 #135) — 인증 종류·대상·면제 사유(`PLATFORM_CODE_SETS`). 권한은 상품 조회(`product:r`)다 */
+    codes: {
+      list: (setId: string) =>
+        storeHttp.request("GET", path`/codes/${setId}`, z.array(platformCodeSchema)),
+    },
+
+    /**
+     * 안내 섹션(이슈 #135) — 여러 상품이 같이 쓰는 글. 상품은 `infoSectionIds`로 연결만 하고, 섹션을 고치면 연결 상품 전체가 바뀐다.
+     * 지우면 연결도 풀린다. 권한은 상품과 같다(`product:r`·`product:rw`)
+     */
+    infoSections: {
+      list: () => storeHttp.request("GET", "/info-sections", z.array(infoSectionSchema)),
+      get: (infoSectionId: string) =>
+        storeHttp.request("GET", path`/info-sections/${infoSectionId}`, infoSectionSchema),
+      create: (body: InfoSectionRequestInput) =>
+        storeHttp.request("POST", "/info-sections", infoSectionSchema, {
+          body: infoSectionRequestSchema.parse(body),
+        }),
+      update: (infoSectionId: string, body: InfoSectionRequestInput) =>
+        storeHttp.request("PUT", path`/info-sections/${infoSectionId}`, infoSectionSchema, {
+          body: infoSectionRequestSchema.parse(body),
+        }),
+      remove: (infoSectionId: string) =>
+        storeHttp.requestVoid("DELETE", path`/info-sections/${infoSectionId}`),
+    },
+
     /**
      * 컬렉션 (이슈 #83) — 상품을 어디에 보여 줄지 정하는 묶음(다대다). 권한은 카테고리와 같다(`category:r`·`category:rw`).
      * 쓰기마다 `revision`이 오른다. 수정 본문에 읽은 `revision`을 주면 그 사이 다른 수정이 있을 때 409 `COLLECTION_CHANGED`다.
@@ -753,6 +822,24 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("DELETE", path`/categories/${categoryId}`, {
           query: (opts?.strategy ? { strategy: opts.strategy } : {}) as Query,
         }),
+      /** 번역(이슈 #134) — 언어별 이름·SEO */
+      localizations: {
+        list: (categoryId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/categories/${categoryId}/localizations`,
+            z.array(categoryLocalizationSchema),
+          ),
+        put: (categoryId: string, locale: string, body: CategoryLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/categories/${categoryId}/localizations/${locale}`,
+            categoryLocalizationSchema,
+            { body: categoryLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (categoryId: string, locale: string) =>
+          storeHttp.requestVoid("DELETE", path`/categories/${categoryId}/localizations/${locale}`),
+      },
     },
 
     orders: {
@@ -1172,7 +1259,7 @@ export function createStoreClient(options: StoreClientOptions) {
         ),
       /**
        * `POST /v1/customers/{customerId}/points/adjustments` (201) — 스코프 `promotion:rw`. 양수 지급, 음수 차감. `idempotencyKey`가 필수다.
-       * 에러: 409 `POINT_BALANCE_INSUFFICIENT`·`POINTS_UNAVAILABLE`, 400 `POINT_EXPIRY_REQUIRED`. 에이전트 요청은 승인 대상이다
+       * 에러: 409 `POINT_BALANCE_INSUFFICIENT`, 400 `POINT_EXPIRY_REQUIRED`. 에이전트 요청은 승인 대상이다
        */
       adjustPoints: (customerId: string, body: PointAdjustmentRequest, idempotencyKey: string) =>
         storeHttp.request(
@@ -1476,14 +1563,13 @@ export function createStoreClient(options: StoreClientOptions) {
        * - 409 `PAYMENT_PROVIDER_INCOMPLETE`: 켜려는데 활성 환경(샌드박스면 TEST, 아니면 LIVE) 세트가 없거나 불완전
        * - 409 `LIVE_GATE_NOT_MET`: `sandboxMode: false`(라이브 전환)인데 개방 조건 미충족. `ApiError.details`가
        *   `{ conditions: LiveGateCondition[] }`(조건별 `met`)이다. `liveGateErrorDetailsSchema`로 파싱한다
-       * - 409 `LIVE_PAYMENTS_DISABLED`: 플랫폼 실결제 스위치만 미충족. `details`는 위와 같다
        *
        * `sandboxMode: true`는 항상 허용되고 즉시 실결제가 멈춘다.
        */
       updateProvider: updatePaymentProvider,
       /**
        * 샌드박스 스위치만 바꾼다 — `updateProvider(provider, { sandboxMode })`와 같다.
-       * `false`(라이브 전환)는 409 `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`(둘 다 `ApiError.details.conditions`)가 날 수 있다.
+       * `false`(라이브 전환)는 409 `LIVE_GATE_NOT_MET`(`ApiError.details.conditions`)가 날 수 있다.
        */
       setSandboxMode: (provider: PgProvider, sandboxMode: boolean) =>
         updatePaymentProvider(provider, { sandboxMode }),
@@ -1933,7 +2019,7 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("PUT", "/storefront/template", storeTemplateSchema, {
           body: updateStoreTemplateRequestSchema.parse(body),
         }),
-      /** `GET /v1/storefront/site` — 스위치 상태와 현재 사이트(없으면 `site: null`) */
+      /** `GET /v1/storefront/site` — 호스팅 설정과 현재 사이트(없으면 `site: null`) */
       get: () => storeHttp.request("GET", "/storefront/site", storefrontHostingSchema),
       /** `GET /v1/storefront/slug-availability?slug=` — 슬러그를 쓸 수 있는가 */
       checkSlug: (slug: string) =>
@@ -2204,7 +2290,7 @@ export function createStoreClient(options: StoreClientOptions) {
       getPointPolicy: () => storeHttp.request("GET", "/store/point-policy", storePointPolicySchema),
       /**
        * `PUT /v1/store/point-policy` — 스코프 `promotion:rw`. 준 항목만 바꾼다. 에이전트 요청은 승인 대상이다.
-       * 에러: 409 `POINTS_UNAVAILABLE`(준비 중) · 400 `POINT_EXPIRY_REQUIRED`(리뷰 적립을 켜는데 유효 기간이 없음)
+       * 에러: 400 `POINT_EXPIRY_REQUIRED`(리뷰 적립을 켜는데 유효 기간이 없음)
        */
       updatePointPolicy: (body: UpdatePointPolicyRequest) =>
         storeHttp.request("PUT", "/store/point-policy", storePointPolicySchema, {

package/src/http.ts

@@ -12,7 +12,7 @@ export const errorDetailSchema = z.object({
    */
   docs: z.url().optional().catch(undefined),
   /**
-   * 에러 코드별 보조 데이터(선택). 예: 관리 API `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의
+   * 에러 코드별 보조 데이터(선택). 예: 관리 API `LIVE_GATE_NOT_MET`의
    * `{ conditions: LiveGateCondition[] }`. 형태는 에러 코드마다 다르므로 소비측이 코드별 스키마로 다시 파싱한다
    */
   details: z.record(z.string(), z.unknown()).optional().catch(undefined),

package/src/index.ts

@@ -36,6 +36,7 @@ export * from "./schemas/customer";
 export * from "./schemas/customer-delegation";
 export * from "./schemas/fulfillment";
 export * from "./schemas/inventory";
+export * from "./schemas/locale";
 export * from "./schemas/login";
 export * from "./schemas/market";
 export * from "./schemas/misc";
@@ -43,6 +44,8 @@ export * from "./schemas/order";
 export * from "./schemas/payment";
 export * from "./schemas/points";
 export * from "./schemas/product";
+export * from "./schemas/product-info";
+export * from "./schemas/product-localization";
 export * from "./schemas/promotion";
 export * from "./schemas/refund-policy";
 export * from "./schemas/saved-option-set";

package/src/schemas/category.ts

@@ -146,3 +146,28 @@ export const categoryDeleteQuerySchema = z.object({
         "`reparent`는 직계 자식을 삭제할 카테고리의 부모로 옮기고, `cascade`는 서브트리를 삭제하고 연결 상품을 미분류로 둔다",
     ),
 });
+
+/**
+ * 카테고리 번역 (이슈 #134) — 언어 하나의 이름·SEO. 카테고리 필드(`name`·`meta*`)는 상점 기본 언어 값이고 번역 레코드가 언어별 값이다.
+ * 비운 칸(null)은 스토어프론트가 기본 언어 값으로 대체한다(칸 단위 대체).
+ */
+export const categoryLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  name: z.string().nullable().describe("이름. null이면 기본 언어 이름"),
+  metaTitle: z.string().nullable(),
+  metaDescription: z.string().nullable(),
+  metaKeywords: z.string().nullable(),
+  updatedAt: z.string(),
+});
+
+export type CategoryLocalization = z.infer<typeof categoryLocalizationSchema>;
+
+/** `PUT /v1/categories/{categoryId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 빠진 칸은 null(기본 언어 값으로 대체)이다 */
+export const categoryLocalizationRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(100).nullable().optional(),
+  metaTitle: z.string().max(100).nullable().optional(),
+  metaDescription: z.string().max(300).nullable().optional(),
+  metaKeywords: z.string().max(200).nullable().optional(),
+});
+
+export type CategoryLocalizationRequest = z.infer<typeof categoryLocalizationRequestSchema>;

package/src/schemas/locale.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+/**
+ * 언어 코드 (이슈 #134) — BCP 47의 언어[-문자][-지역]까지 받는다(`ko`·`en`·`en-US`·`zh-Hant-TW`).
+ * 대소문자는 표준 표기로 맞춘다(언어 소문자, 문자 첫 글자 대문자, 지역 대문자). 맞지 않으면 null이다.
+ */
+const LOCALE_PATTERN = /^([a-z]{2,3})(?:-([a-z]{4}))?(?:-([a-z]{2}))?$/;
+
+export function normalizeLocale(value: string | null | undefined): string | null {
+  const match = value?.trim().replace(/_/g, "-").toLowerCase().match(LOCALE_PATTERN);
+  if (!match) return null;
+  const [, language, script, region] = match;
+  return [
+    language,
+    script ? `${script[0]?.toUpperCase()}${script.slice(1)}` : null,
+    region ? region.toUpperCase() : null,
+  ]
+    .filter(Boolean)
+    .join("-");
+}
+
+/** 상점 기본 언어 — 옛 상점과 언어를 정하지 않은 상점의 값이다 */
+export const DEFAULT_STORE_LOCALE = "ko";
+
+export const localeCodeSchema = z
+  .string()
+  .max(35)
+  .transform((value, ctx) => {
+    const normalized = normalizeLocale(value);
+    if (normalized === null) {
+      ctx.addIssue({
+        code: "custom",
+        message: "언어는 BCP 47 언어 코드입니다(예: ko·en·en-US)",
+      });
+      return z.NEVER;
+    }
+    return normalized;
+  })
+  .describe("언어(BCP 47, 예: ko·en·en-US·zh-Hant-TW)");

package/src/schemas/market.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { currencyCodeSchema } from "./currency";
+import { localeCodeSchema } from "./locale";
 
 /**
  * 판매 권역 (이슈 #130) — 상점이 어느 국가에 어느 통화로 파는지를 정한다.
@@ -9,6 +10,8 @@ import { currencyCodeSchema } from "./currency";
  *
  * 스토어프론트는 요청마다 도메인(`X-Storefront-Host`) → 구매자 국가(`X-Buyer-Country`) → 기본 권역 순으로 권역을 고르고, 주문서가 그 권역·통화를 굳힌다.
  * 외화 권역은 적립금을 켤 수 없다(적립금은 기본 통화 단위다).
+ *
+ * 권역은 언어도 정한다(이슈 #134). `locales`는 이 권역 스토어프론트가 내는 언어이고 첫 언어가 대표 언어다. 비어 있으면 상점 기본 언어 하나다.
  */
 
 const countryCodeSchema = z
@@ -44,6 +47,13 @@ export const marketSchema = z.object({
     .string()
     .nullable()
     .describe("보관 시각. 보관한 권역은 판정에서 빠지고 그 국가·도메인은 풀린다"),
+  locales: z
+    .array(z.string())
+    .optional()
+    .default([])
+    .describe(
+      "이 권역 언어(이슈 #134). 첫 언어가 대표 언어다. 비어 있으면 상점 기본 언어 하나다. 서버는 항상 싣는다",
+    ),
 });
 
 export type Market = z.infer<typeof marketSchema>;
@@ -55,6 +65,13 @@ export const createMarketRequestSchema = z.strictObject({
   domains: z.array(hostnameSchema).max(20).optional(),
   couponsEnabled: z.boolean().optional().describe("기본 false"),
   pointsEnabled: z.boolean().optional().describe("기본 false. 외화 권역은 true로 둘 수 없다"),
+  locales: z
+    .array(localeCodeSchema)
+    .max(20)
+    .optional()
+    .describe(
+      "이 권역 언어(이슈 #134). 주면 목록 전체를 바꾼다. 첫 언어가 대표 언어다. 비우면 상점 기본 언어 하나다",
+    ),
 });
 
 export type CreateMarketRequest = z.infer<typeof createMarketRequestSchema>;
@@ -70,6 +87,13 @@ export const updateMarketRequestSchema = z.strictObject({
   domains: z.array(hostnameSchema).max(20).optional().describe("주면 도메인 목록 전체를 바꾼다"),
   couponsEnabled: z.boolean().optional(),
   pointsEnabled: z.boolean().optional().describe("외화 권역은 true로 둘 수 없다"),
+  locales: z
+    .array(localeCodeSchema)
+    .max(20)
+    .optional()
+    .describe(
+      "이 권역 언어(이슈 #134). 주면 목록 전체를 바꾼다. 첫 언어가 대표 언어다. 비우면 상점 기본 언어 하나다",
+    ),
 });
 
 export type UpdateMarketRequest = z.infer<typeof updateMarketRequestSchema>;

package/src/schemas/order.ts

@@ -284,6 +284,13 @@ export const orderSchema = z.object({
     .describe(
       "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았습니다. 상품을 발송하지 않도록 주의하십시오",
     ),
+  locale: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "구매 언어(이슈 #134, BCP 47). 주문상품의 상품명·옵션 이름은 구매자가 이 언어로 본 값이다. null이면 상점 기본 언어다(언어 기능 이전 주문 포함)",
+    ),
   items: z.array(orderItemSchema),
 });
 
@@ -310,7 +317,7 @@ const pageQuery = {
 
 /**
  * `GET /v1/orders` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 검증 규칙은 서버가 적용한다:
- * `orderNo` 없이 `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜·`orderNo` 형식 오류 400 `INVALID_PARAMETER`, 31일 초과 400 `RANGE_TOO_WIDE`,
+ * `orderNo` 없이 `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜·`orderNo` 형식 오류 400 `INVALID_PARAMETER`, 366일 초과 400 `RANGE_TOO_WIDE`,
  * `testPayment`가 `true`·`false`가 아니면 400 `INVALID_PARAMETER`
  */
 export const orderListQuerySchema = z.object({
@@ -321,7 +328,7 @@ export const orderListQuerySchema = z.object({
   orderedTo: z
     .string()
     .optional()
-    .describe("조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 31일"),
+    .describe("조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 366일"),
   status: orderItemStatusSchema
     .optional()
     .describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),

package/src/schemas/payment.ts

@@ -410,7 +410,7 @@ export const liveGateConditionCodeSchema = z
   .describe(
     "라이브 개방 조건. `TEST_CONNECTION`=TEST 세트 연결 테스트 성공, `SANDBOX_PAYMENT`=현재 TEST 세트로 샌드박스 결제 1건 승인, " +
       "`SANDBOX_REFUND`=그 샌드박스 결제의 환불 1건 성공, `LIVE_CONNECTION`=LIVE 세트 연결 테스트 성공, " +
-      "`PLATFORM_LIVE_ENABLED`=플랫폼이 실결제를 열어 둠, `NOT_TEMPLATE_STORE`=템플릿 상점이 아님(템플릿 상점에만 싣고 늘 미충족), " +
+      "`PLATFORM_LIVE_ENABLED`=플랫폼이 실결제를 열어 둠(늘 충족), `NOT_TEMPLATE_STORE`=템플릿 상점이 아님(템플릿 상점에만 싣고 늘 미충족), " +
       "`NOT_DEVELOPMENT_STORE`=앱 개발 상점이 아님(앱 개발 상점에만 싣고 늘 미충족)",
   );
 export type LiveGateConditionCode = z.infer<typeof liveGateConditionCodeSchema>;
@@ -432,7 +432,7 @@ export const liveGateSchema = z.object({
 export type LiveGate = z.infer<typeof liveGateSchema>;
 
 /**
- * 409 `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의 `ApiError.details` 형태.
+ * 409 `LIVE_GATE_NOT_MET`의 `ApiError.details` 형태.
  * 응답 파싱용이라 관대하다 — 알 수 없는 키는 버리고, 형태가 다르면 safeParse 실패로 처리한다.
  */
 export const liveGateErrorDetailsSchema = z.object({

package/src/schemas/points.ts

@@ -210,9 +210,7 @@ export type PointPolicyNotice = z.infer<typeof pointPolicyNoticeSchema>;
 export const storePointPolicySchema = z.object({
   available: z
     .boolean()
-    .describe(
-      "적립금 설정을 바꿀 수 있는가. false면 준비 중이라 정책 저장이 409 `POINTS_UNAVAILABLE`이고 모든 적립이 멈춰 있다",
-    ),
+    .describe("적립금 설정을 바꿀 수 있는가. 지금은 늘 true다(이전 응답 호환 필드)"),
   configured: z.boolean().describe("셀러가 정책을 저장한 적이 있는가. false면 기본(모두 끔)이다"),
   reviewReward: reviewRewardPolicySchema.describe("리뷰 적립. 정하지 않았으면 끔·0원"),
   purchaseEarn: purchaseEarnPolicySchema.describe(
@@ -223,8 +221,7 @@ export const storePointPolicySchema = z.object({
     .optional()
     .default(false)
     .describe(
-      "적립금 사용(결제에 쓰기)을 켤 수 있는가 (#93). false면 준비 중이라 `use.enabled`를 켜는 저장이 409 `POINTS_UNAVAILABLE`이다. " +
-        "필드가 없는 이전 응답은 false로 읽는다",
+      "적립금 사용(결제에 쓰기)을 켤 수 있는가 (#93). 지금은 늘 true다. 필드가 없는 이전 응답은 false로 읽는다",
     ),
   use: pointUsePolicySchema
     .optional()

package/src/schemas/product-info.ts

@@ -0,0 +1,190 @@
+import { z } from "zod";
+
+/**
+ * 상품정보제공 고시·인증 정보·안내 섹션 (이슈 #135).
+ *
+ * **코드 값은 문자열이다.** 품목군(`schemaId`)·인증 종류·대상·면제 사유는 플랫폼 코드 표(서버 DB)가 원천이고, 코드가 늘어도 이 SDK의
+ * 계약이 깨지지 않게 zod enum으로 막지 않는다. 서버가 코드 표에 있는지 검사한다(없으면 400 `INVALID_INFO_CODE`).
+ * enum으로 두는 값은 서버가 그 값으로 분기하는 인증 상태(`CERTIFICATION_STATUSES`)뿐이다.
+ */
+
+// ── 플랫폼 코드 표 ────────────────────────────────────────────────
+
+/**
+ * 칸 값의 출처 — 셀러가 비운 칸을 서버가 채운다. 서버가 분기하는 값이라 형태가 정해져 있지만, 새 출처가 늘 수 있어 응답은 열린 객체다.
+ * - `legal`: 법정 문구(`text`). 셀러가 적지 않는다
+ * - `option`: 이름이 `names` 중 하나인 조합 옵션명의 값 목록
+ * - `store`: 상점 필드(`field`, 예: `customerCenterPhone`)
+ */
+export const infoFieldSourceSchema = z.looseObject({
+  type: z.string(),
+  text: z.string().optional(),
+  names: z.array(z.string()).optional(),
+  field: z.string().optional(),
+});
+
+export type InfoFieldSource = z.infer<typeof infoFieldSourceSchema>;
+
+export const infoSchemaFieldSchema = z.object({
+  key: z.string(),
+  label: z.string(),
+  required: z
+    .boolean()
+    .describe("법정 필수 칸인가. 서버는 비어 있어도 막지 않는다(표시는 「상품상세 참조」)"),
+  maxLength: z.number().int(),
+  source: infoFieldSourceSchema.nullable().optional().describe("값 출처. 없으면 셀러가 적는 칸"),
+});
+
+export type InfoSchemaField = z.infer<typeof infoSchemaFieldSchema>;
+
+/** 정형 정보 스키마 — 고시 품목군 하나(`kind: "notice"`). 칸 구성은 버전마다 고정이고 상품은 저장한 버전으로 표시된다 */
+export const infoSchemaSchema = z.object({
+  schemaId: z.string().describe("품목군 코드(예: `WEAR`)"),
+  version: z.number().int(),
+  kind: z.string().describe("스키마 종류. 지금은 `notice`(상품정보제공 고시)"),
+  name: z.string(),
+  fallback: z.string().describe("비운 칸의 표시 문구(예: 「상품상세 참조」)"),
+  fields: z.array(infoSchemaFieldSchema).describe("칸. 배열 순서가 표시 순서다"),
+});
+
+export type InfoSchema = z.infer<typeof infoSchemaSchema>;
+
+/** 플랫폼 코드 하나 — 코드 묶음(`setId`) 안에서 유일하다. `attrs`는 묶음마다 다른 부가 정보다 */
+export const platformCodeSchema = z.object({
+  code: z.string(),
+  label: z.string(),
+  attrs: z
+    .record(z.string(), z.unknown())
+    .describe(
+      "부가 정보. `certification.subject`는 `kinds`(이 대상을 충족하는 인증 종류)·`exemptions`(허용 면제 사유)를 싣는다",
+    ),
+});
+
+export type PlatformCode = z.infer<typeof platformCodeSchema>;
+
+/** 코드 묶음 — `GET /v1/codes/{setId}` */
+export const PLATFORM_CODE_SETS = {
+  certificationKind: "certification.kind",
+  certificationSubject: "certification.subject",
+  certificationExemption: "certification.exemption",
+} as const;
+
+// ── 상품 고시 ────────────────────────────────────────────────────
+
+export const productNoticeSchema = z.object({
+  schemaId: z.string(),
+  version: z.number().int(),
+  values: z.record(z.string(), z.string()).describe("칸 키 → 셀러가 적은 값. 비운 칸은 없다"),
+});
+
+export type ProductNotice = z.infer<typeof productNoticeSchema>;
+
+export const MAX_NOTICE_VALUE_LENGTH = 1500;
+
+export const productNoticeRequestSchema = z.object({
+  schemaId: z.string().trim().min(1).max(50).describe("품목군 코드(`GET /v1/info-schemas`)"),
+  version: z.number().int().positive().optional().describe("품목군 버전. 생략하면 현재 버전"),
+  values: z
+    .record(z.string().max(50), z.string().max(MAX_NOTICE_VALUE_LENGTH))
+    .default({})
+    .describe(
+      "칸 키 → 값. 출처가 `legal`인 칸은 받지 않는다(400). 빈 문자열은 비운 칸으로 저장하지 않는다. 칸 길이는 스키마 `maxLength`",
+    ),
+});
+
+export type ProductNoticeRequest = z.infer<typeof productNoticeRequestSchema>;
+
+// ── 상품 인증 ────────────────────────────────────────────────────
+
+/** 인증 대상 상태 — 서버가 분기한다(대상이면 인증서 필수, 면제면 사유 필수) */
+export const CERTIFICATION_STATUSES = ["REQUIRED", "NOT_REQUIRED", "EXEMPT"] as const;
+
+export type CertificationStatus = (typeof CERTIFICATION_STATUSES)[number];
+
+export const MAX_CERTIFICATION_ITEMS = 20;
+
+export const productCertificationsSchema = z.object({
+  subjects: z
+    .array(
+      z.object({
+        subject: z.string().describe("인증 대상 코드(`certification.subject`)"),
+        status: z
+          .string()
+          .describe("`REQUIRED`·`NOT_REQUIRED`·`EXEMPT`. 값이 늘 수 있어 문자열이다"),
+        exemption: z.string().nullable().describe("면제 사유 코드. `EXEMPT`일 때만 있다"),
+      }),
+    )
+    .describe("인증 대상 여부. 없는 대상은 `NOT_REQUIRED`다"),
+  items: z
+    .array(
+      z.object({
+        kind: z.string().describe("인증 종류 코드(`certification.kind`)"),
+        agency: z.string().nullable().describe("인증 기관"),
+        number: z.string().describe("인증 번호"),
+      }),
+    )
+    .describe("인증서. 배열 순서가 표시 순서다"),
+});
+
+export type ProductCertifications = z.infer<typeof productCertificationsSchema>;
+
+export const productCertificationsRequestSchema = z.object({
+  subjects: z
+    .array(
+      z.object({
+        subject: z.string().trim().min(1).max(50),
+        status: z.enum(CERTIFICATION_STATUSES),
+        exemption: z.string().trim().min(1).max(50).nullish(),
+      }),
+    )
+    .max(20)
+    .default([])
+    .describe(
+      "인증 대상 여부. `REQUIRED`인데 그 대상의 인증 종류(`attrs.kinds`) 인증서가 `items`에 없으면 400 `CERTIFICATION_REQUIRED`, " +
+        "`EXEMPT`인데 사유가 없거나 대상이 허용하지 않는 사유면 400 `CERTIFICATION_EXEMPTION_INVALID`",
+    ),
+  items: z
+    .array(
+      z.object({
+        kind: z.string().trim().min(1).max(50),
+        agency: z.string().trim().max(100).nullish(),
+        number: z.string().trim().min(1).max(100),
+      }),
+    )
+    .max(MAX_CERTIFICATION_ITEMS)
+    .default([]),
+});
+
+export type ProductCertificationsRequest = z.infer<typeof productCertificationsRequestSchema>;
+export type ProductCertificationsRequestInput = z.input<typeof productCertificationsRequestSchema>;
+
+// ── 안내 섹션 ────────────────────────────────────────────────────
+
+/** 상품 하나에 연결할 수 있는 안내 섹션 수 */
+export const MAX_PRODUCT_INFO_SECTIONS = 10;
+export const MAX_INFO_SECTION_TITLE = 100;
+
+/**
+ * 안내 섹션 — 사이즈 가이드·세탁 안내처럼 여러 상품이 같이 쓰는 글이다. **상품은 연결만 한다**(복사가 아니다).
+ * 섹션을 고치면 연결된 모든 상품의 표시가 바뀐다.
+ */
+export const infoSectionSchema = z.object({
+  infoSectionId: z.string(),
+  title: z.string(),
+  body: z.string().describe("본문 HTML(상세설명과 같은 정화 규칙)"),
+  bodyJson: z.string().nullable().describe("에디터 복원용 직렬화 상태"),
+  assignedProductCount: z.number().int().describe("이 섹션을 연결한 상품 수"),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export type InfoSection = z.infer<typeof infoSectionSchema>;
+
+export const infoSectionRequestSchema = z.object({
+  title: z.string().trim().min(1).max(MAX_INFO_SECTION_TITLE),
+  body: z.string().default(""),
+  bodyJson: z.string().nullable().optional(),
+});
+
+export type InfoSectionRequest = z.infer<typeof infoSectionRequestSchema>;
+export type InfoSectionRequestInput = z.input<typeof infoSectionRequestSchema>;

package/src/schemas/product-localization.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { MAX_PRODUCT_IMAGES, productImageUrlSchema } from "./product";
+
+/**
+ * 상품 번역 (이슈 #134) — 언어 하나의 상품명·상세설명·이미지·옵션 이름. 상품 필드는 상점 기본 언어 값이고 번역 레코드가 언어별 값이다.
+ * 비운 칸(null)은 스토어프론트가 기본 언어 값으로 대체한다(칸 단위 대체). 이미지는 목록 통째로 대체한다.
+ * 옵션은 id가 원천이다 — 값 id·추가금·재고는 언어와 무관하고 이름만 언어별이다.
+ */
+
+const translatedOptionValueSchema = z.object({
+  valueId: z.string(),
+  name: z.string().nullable().describe("값 이름. null이면 기본 언어 이름"),
+});
+
+const translatedOptionGroupSchema = z.object({
+  groupId: z.string(),
+  name: z.string().nullable().describe("옵션명. null이면 기본 언어 이름"),
+  values: z.array(translatedOptionValueSchema),
+});
+
+const translatedCustomInputSchema = z.object({
+  inputId: z.string(),
+  label: z.string().nullable().describe("항목명. null이면 기본 언어 항목명"),
+  placeholder: z.string().nullable().describe("입력 안내. null이면 기본 언어 안내"),
+});
+
+/**
+ * 조회 응답 — 지금 상품의 옵션명·값·직접 입력 항목을 모두 싣고 번역하지 않은 칸은 null이다.
+ * `optionGroups`는 조합 옵션, `addonGroups`는 추가 선택이다(상품 응답과 같은 구분)
+ */
+export const productLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  name: z.string().nullable().describe("상품명. null이면 기본 언어 상품명"),
+  description: z.string().nullable().describe("상세설명(HTML). null이면 기본 언어 상세설명"),
+  descriptionJson: z.string().nullable().describe("상세설명 에디터 상태(재편집 복원용)"),
+  images: z.array(z.string()).nullable().describe("이미지 목록. null이면 기본 언어 목록"),
+  optionGroups: z.array(translatedOptionGroupSchema),
+  addonGroups: z.array(translatedOptionGroupSchema),
+  customInputs: z.array(translatedCustomInputSchema),
+  updatedAt: z.string(),
+});
+
+export type ProductLocalization = z.infer<typeof productLocalizationSchema>;
+
+const translatedNameSchema = z.string().trim().min(1).max(50).nullable().optional();
+
+const translatedOptionGroupRequestSchema = z.strictObject({
+  groupId: z.string(),
+  name: translatedNameSchema,
+  values: z.array(z.strictObject({ valueId: z.string(), name: translatedNameSchema })).optional(),
+});
+
+/**
+ * `PUT /v1/products/{productId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 빠진 칸은 null(기본 언어 값으로 대체)이다.
+ * 옵션은 번역할 id만 보낸다. 상품에 없는 id는 400 `PRODUCT_LOCALIZATION_TARGET_NOT_FOUND`다.
+ * 번역한 옵션명·값 이름도 기본 언어와 같은 규칙(대소문자·앞뒤 공백 무시 유일)이고 겹치면 400 `INVALID_OPTION_MODEL`이다
+ */
+export const productLocalizationRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(100).nullable().optional(),
+  description: z.string().nullable().optional(),
+  descriptionJson: z.string().nullable().optional(),
+  images: z.array(productImageUrlSchema).min(1).max(MAX_PRODUCT_IMAGES).nullable().optional(),
+  optionGroups: z.array(translatedOptionGroupRequestSchema).optional(),
+  addonGroups: z.array(translatedOptionGroupRequestSchema).optional(),
+  customInputs: z
+    .array(
+      z.strictObject({
+        inputId: 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 ProductLocalizationRequest = z.infer<typeof productLocalizationRequestSchema>;