@sayren/store-sdk 0.33.0 → 0.34.0

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.ts

@@ -14,6 +14,13 @@ import {
   productFulfillmentUpdateSchema,
 } from "./fulfillment";
 import { pointEarnRateBpSchema } from "./points";
+import {
+  MAX_PRODUCT_INFO_SECTIONS,
+  productCertificationsRequestSchema,
+  productCertificationsSchema,
+  productNoticeRequestSchema,
+  productNoticeSchema,
+} from "./product-info";
 import { productRefundPolicyPatchSchema } from "./refund-policy";
 import { inventoryModeSchema } from "./stay";
 import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
@@ -445,6 +452,19 @@ export const productSchema = productSummarySchema.extend({
     .describe(
       "설정된 즉시할인. GET /v1/products/{productId}/discount 응답과 같은 형태다. 할인이 없으면 null",
     ),
+  notice: productNoticeSchema
+    .nullable()
+    .optional()
+    .describe("상품정보제공 고시(이슈 #135). 없으면 null. 서버는 항상 싣는다"),
+  certifications: productCertificationsSchema
+    .nullable()
+    .optional()
+    .describe("인증 정보(이슈 #135). 없으면 null. 서버는 항상 싣는다"),
+  infoSectionIds: z
+    .array(z.string())
+    .optional()
+    .default([])
+    .describe("연결한 안내 섹션 id(이슈 #135). 배열 순서가 표시 순서다. 서버는 항상 싣는다"),
   createdAt: z.string().optional(),
 });
 
@@ -569,14 +589,14 @@ export const optionModelRequestSchema = z.object({
     .max(MAX_ADDON_GROUPS)
     .optional()
     .describe(
-      "추가 선택 옵션명 전체(이슈 #59). 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 끄려면 빈 배열을 보낸다. 기능이 열리기 전에는 비어 있지 않은 값이 409 `OPTION_ADDONS_UNAVAILABLE`이다",
+      "추가 선택 옵션명 전체(이슈 #59). 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 끄려면 빈 배열을 보낸다",
     ),
   customInputs: z
     .array(customInputRequestSchema)
     .max(MAX_CUSTOM_INPUTS)
     .optional()
     .describe(
-      "직접 입력 항목 전체(이슈 #59). 배열 순서가 표시 순서다. 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 항목명에 개인정보성 단어(`CUSTOM_INPUT_FORBIDDEN_WORDS`)가 있으면 400 `CUSTOM_INPUT_LABEL_FORBIDDEN`, 기능이 열리기 전에는 비어 있지 않은 값이 409 `OPTION_ADDONS_UNAVAILABLE`이다",
+      "직접 입력 항목 전체(이슈 #59). 배열 순서가 표시 순서다. 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 항목명에 개인정보성 단어(`CUSTOM_INPUT_FORBIDDEN_WORDS`)가 있으면 400 `CUSTOM_INPUT_LABEL_FORBIDDEN`이다",
     ),
   optionSort: optionSortSchema
     .optional()
@@ -694,6 +714,25 @@ const productWriteShape = {
       "상품별 환불 정책 — 준 항목만 상점 기본을 덮어쓴다. `null`이나 생략은 상점 기본을 그대로 쓴다는 뜻이다. " +
         "반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 줄 수 있다(다른 유형은 400)",
     ),
+  notice: productNoticeRequestSchema
+    .nullable()
+    .optional()
+    .describe(
+      "상품정보제공 고시(이슈 #135). `null`은 지운다. 등록에서 생략하면 없음, 전체 수정(PUT)에서 생략하면 지금 값을 유지한다",
+    ),
+  certifications: productCertificationsRequestSchema
+    .nullable()
+    .optional()
+    .describe(
+      "인증 정보(이슈 #135). `null`은 지운다. 등록에서 생략하면 없음, 전체 수정(PUT)에서 생략하면 지금 값을 유지한다",
+    ),
+  infoSectionIds: z
+    .array(z.string().min(1))
+    .max(MAX_PRODUCT_INFO_SECTIONS)
+    .optional()
+    .describe(
+      "연결할 안내 섹션 id(이슈 #135). 배열 순서가 표시 순서다. 이 상점의 섹션이 아니면 400 `INFO_SECTION_NOT_FOUND`. 전체 수정(PUT)에서 생략하면 지금 연결을 유지한다",
+    ),
   ...optionModelRequestSchema.shape,
   sourceOptionSetIds: z
     .array(z.string())

package/src/schemas/storefront-hosting.ts

@@ -13,7 +13,6 @@ import { RESERVED_STORE_CODES } from "./store";
  * 공개 전환·슬러그 변경·호스팅 끄기는 승인(`APPROVAL_REQUIRED`)이다 — 구매자가 보는 화면을 바꾸는 쓰기다.
  *
  * 오류 코드:
- * - 403 `STOREFRONT_HOSTING_DISABLED` — 플랫폼 스위치가 꺼져 새 사이트를 만들 수 없다
  * - 404 `STOREFRONT_SITE_NOT_FOUND` · `STOREFRONT_TEMPLATE_NOT_FOUND` · `STOREFRONT_VERSION_NOT_FOUND`
  * - 409 `STOREFRONT_SITE_EXISTS` — 이미 사이트가 있다(상점당 1개)
  * - 409 `STOREFRONT_SLUG_TAKEN` — 다른 사이트가 쓰거나 보류 중인 슬러그다
@@ -30,7 +29,7 @@ import { RESERVED_STORE_CODES } from "./store";
  * - 503 `STOREFRONT_PREVIEW_NOT_CONFIGURED` — 미리보기 서명 키가 설정되지 않았다
  *
  * 편집(M2b, `/v1/storefront/site/editing`·`files/**`·`checks/**`·`verify`·`builds/**`, 버전 만들기):
- * - 403 `STOREFRONT_EDITING_DISABLED` — 플랫폼 편집 스위치가 꺼져 있다
+ * - 403 `STOREFRONT_EDITING_DISABLED` — 편집을 쓸 수 없어 셀러 템플릿으로 사이트를 만들 수 없다(사이트 만들기)
  * - 503 `STOREFRONT_EDITING_NOT_CONFIGURED` — 편집 Sandbox가 설정되지 않았다
  * - 409 `EDIT_CAPACITY_FULL` — 플랫폼 전체 동시 편집 상한에 걸렸다. `error.details.retryAfterSeconds` 뒤에 다시 한다
  * - 409 `EDIT_SESSION_REQUIRED` — 편집 미리보기 링크: 편집 환경이 없다
@@ -392,13 +391,11 @@ export const storefrontSiteSchema = z.object({
 });
 export type StorefrontSite = z.infer<typeof storefrontSiteSchema>;
 
-/** `GET /v1/storefront/site` — 스위치 상태와 현재 사이트(없으면 null. 끈 사이트는 싣지 않는다) */
+/** `GET /v1/storefront/site` — 호스팅 설정과 현재 사이트(없으면 null. 끈 사이트는 싣지 않는다) */
 export const storefrontHostingSchema = z.object({
-  enabled: z.boolean().describe("새 사이트를 만들 수 있는가 (플랫폼 스위치)"),
+  enabled: z.boolean().describe("새 사이트를 만들 수 있는가 (항상 true)"),
   domain: z.string().describe("호스팅 도메인 (예: `sayren.co`). 사이트 주소는 `{slug}.{domain}`"),
-  editingEnabled: z
-    .boolean()
-    .describe("파일 편집·버전 만들기를 쓸 수 있는가 (플랫폼 편집 스위치와 Sandbox 설정)"),
+  editingEnabled: z.boolean().describe("파일 편집·버전 만들기를 쓸 수 있는가 (Sandbox 설정)"),
   site: storefrontSiteSchema.nullable(),
 });
 export type StorefrontHosting = z.infer<typeof storefrontHostingSchema>;
@@ -574,7 +571,6 @@ export type StorefrontPreviewLink = z.infer<typeof storefrontPreviewLinkSchema>;
 // - 결제 복귀·방문 분석·소셜 로그인 허용 목록은 연결된(`ACTIVE`) 도메인을 자동으로 더한다.
 //
 // 오류 코드:
-// - 403 `STOREFRONT_CUSTOM_DOMAINS_DISABLED` — 플랫폼 스위치가 꺼져 도메인을 추가할 수 없다
 // - 400 `STOREFRONT_DOMAIN_INVALID` — 형식이 틀렸거나 연결할 수 없는 도메인이다(`error.details.reason`)
 // - 404 `STOREFRONT_DOMAIN_NOT_FOUND`
 // - 409 `STOREFRONT_DOMAIN_EXISTS` — 이 상점에 이미 추가한 도메인이다
@@ -798,7 +794,7 @@ export type StorefrontSiteDomain = z.infer<typeof storefrontSiteDomainSchema>;
 
 /** `GET /v1/storefront/site/domains` — 사이트의 주소 목록(기본 주소 + 내 도메인)과 연결 설정 */
 export const storefrontSiteDomainsSchema = z.object({
-  enabled: z.boolean().describe("내 도메인을 추가할 수 있는가 (플랫폼 스위치)"),
+  enabled: z.boolean().describe("내 도메인을 추가할 수 있는가 (항상 true)"),
   limit: z.number().int().min(0).describe("상점당 내 도메인 수 상한 (해제한 도메인은 세지 않는다)"),
   target: z.string().describe("CNAME 대상 (예: `sites.sayren.co`)"),
   domains: z.array(storefrontSiteDomainSchema).describe("대표 주소 먼저, 그다음 추가한 순서"),
@@ -971,7 +967,7 @@ export const storefrontDevLogsSchema = z.object({
 export type StorefrontDevLogs = z.infer<typeof storefrontDevLogsSchema>;
 
 export const storefrontEditingSchema = z.object({
-  enabled: z.boolean().describe("편집을 쓸 수 있는가 (플랫폼 스위치와 Sandbox 설정)"),
+  enabled: z.boolean().describe("편집을 쓸 수 있는가 (Sandbox 설정)"),
   session: storefrontEditSessionSchema
     .nullable()
     .describe("열린 편집 환경. 잠들었거나 닫았으면 null"),