@sayren/store-sdk 0.32.0 → 0.34.0

package/src/schemas/market.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { currencyCodeSchema } from "./currency";
+
+/**
+ * 판매 권역 (이슈 #130) — 상점이 어느 국가에 어느 통화로 파는지를 정한다.
+ *
+ * 권역 = 이름 + 통화 하나 + 국가 목록 + 연결 도메인 + 쿠폰·적립금 사용. 국가는 상점 안에서 한 권역에만 속하고, 판매 국가는 보관하지 않은 모든 권역 국가의
+ * 합집합이다. 기본 권역은 상점마다 하나이고 그 통화가 기본 통화(KRW)다. 기본 권역은 보관할 수 없고 국가 목록을 비울 수 없다. 권역의 통화는 만들 때만 정한다.
+ *
+ * 스토어프론트는 요청마다 도메인(`X-Storefront-Host`) → 구매자 국가(`X-Buyer-Country`) → 기본 권역 순으로 권역을 고르고, 주문서가 그 권역·통화를 굳힌다.
+ * 외화 권역은 적립금을 켤 수 없다(적립금은 기본 통화 단위다).
+ */
+
+const countryCodeSchema = z
+  .string()
+  .regex(/^[A-Za-z]{2}$/, "국가는 ISO 3166-1 alpha-2 두 글자입니다")
+  .transform((value) => value.toUpperCase())
+  .describe("국가(ISO 3166-1 alpha-2, 예: KR·US·JP)");
+
+const hostnameSchema = z
+  .string()
+  .min(1)
+  .max(253)
+  .regex(/^[A-Za-z0-9.-]+$/, "도메인은 호스트 이름만 입력합니다(예: shop.example.com)")
+  .transform((value) => value.toLowerCase().replace(/\.$/, ""))
+  .describe(
+    "연결 도메인(호스트 이름). 셀러가 직접 호스팅하는 스토어프론트가 `X-Storefront-Host`로 보낸다",
+  );
+
+export const marketSchema = z.object({
+  marketId: z.string(),
+  name: z.string(),
+  currency: currencyCodeSchema,
+  isDefault: z
+    .boolean()
+    .describe("기본 권역. 상점마다 하나이고 보관할 수 없다. 이 통화가 기본 통화다"),
+  countries: z.array(z.string()).describe("이 권역 국가. 국가는 상점 안에서 한 권역에만 속한다"),
+  domains: z.array(z.string()).describe("이 권역에 연결한 도메인"),
+  couponsEnabled: z.boolean().describe("이 권역 주문서에서 쿠폰을 쓸 수 있는가"),
+  pointsEnabled: z
+    .boolean()
+    .describe("이 권역 주문서에서 적립금을 쓸 수 있는가. 외화 권역은 늘 false다"),
+  archivedAt: z
+    .string()
+    .nullable()
+    .describe("보관 시각. 보관한 권역은 판정에서 빠지고 그 국가·도메인은 풀린다"),
+});
+
+export type Market = z.infer<typeof marketSchema>;
+
+export const createMarketRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(50),
+  currency: currencyCodeSchema.describe("이 권역의 통화. 만든 뒤에는 바꿀 수 없다"),
+  countries: z.array(countryCodeSchema).min(1).max(250),
+  domains: z.array(hostnameSchema).max(20).optional(),
+  couponsEnabled: z.boolean().optional().describe("기본 false"),
+  pointsEnabled: z.boolean().optional().describe("기본 false. 외화 권역은 true로 둘 수 없다"),
+});
+
+export type CreateMarketRequest = z.infer<typeof createMarketRequestSchema>;
+export type CreateMarketRequestInput = z.input<typeof createMarketRequestSchema>;
+
+export const updateMarketRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(50).optional(),
+  countries: z
+    .array(countryCodeSchema)
+    .max(250)
+    .optional()
+    .describe("주면 국가 목록 전체를 바꾼다. 다른 권역의 국가는 그 권역에서 먼저 빼야 한다"),
+  domains: z.array(hostnameSchema).max(20).optional().describe("주면 도메인 목록 전체를 바꾼다"),
+  couponsEnabled: z.boolean().optional(),
+  pointsEnabled: z.boolean().optional().describe("외화 권역은 true로 둘 수 없다"),
+});
+
+export type UpdateMarketRequest = z.infer<typeof updateMarketRequestSchema>;
+export type UpdateMarketRequestInput = z.input<typeof updateMarketRequestSchema>;

package/src/schemas/order.ts

@@ -21,6 +21,12 @@ export const orderSummarySchema = z.object({
       "진행 중 주문상품 가운데 가장 앞 단계(취소 제외, 모두 취소면 CANCELED, #115). 섞인 주문에서 아직 기다리는 단계다. 서버는 항상 싣는다",
     ),
   orderedAt: z.string(),
+  currency: z
+    .string()
+    .optional()
+    .describe(
+      "주문 통화(ISO 4217, 이슈 #130). 금액 필드는 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 없으면 KRW다. 서버는 항상 싣는다",
+    ),
   testPayment: z
     .boolean()
     .describe(
@@ -33,7 +39,10 @@ export type OrderSummary = z.infer<typeof orderSummarySchema>;
 export const shippingAddressSchema = z.object({
   receiverName: z.string(),
   phone: z.string(),
-  zipCode: z.string(),
+  zipCode: z.string().describe("우편번호. 해외 배송지는 그 나라 우편번호이고 없으면 빈 문자열이다"),
+  countryCode: z.string().optional().describe("배송 국가(이슈 #130). 없으면 국내(KR)다"),
+  region: z.string().nullish().describe("해외 배송지의 1차 행정 구역"),
+  city: z.string().nullish().describe("해외 배송지의 도시. 국내 배송지는 없다"),
   address1: z.string(),
   address2: z.string().nullish(),
   deliveryMemo: z.string().nullish(),
@@ -264,6 +273,12 @@ export const orderSchema = z.object({
         "현금영수증. 구매자가 계좌이체·가상계좌 결제에서 신청했을 때만 있고 그 밖에는 null. 서버는 항상 싣는다",
       ),
   }),
+  currency: z
+    .string()
+    .optional()
+    .describe(
+      "주문 통화(ISO 4217, 이슈 #130). 금액 필드는 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 없으면 KRW다. 서버는 항상 싣는다",
+    ),
   testPayment: z
     .boolean()
     .describe(

package/src/schemas/payment.ts

@@ -10,12 +10,21 @@ import { type PageParams, pageSchema } from "./common";
  */
 
 export const pgProviderSchema = z
-  .enum(["tosspayments", "portone", "kakaopay", "naverpay"])
+  .enum(["tosspayments", "portone", "kakaopay", "naverpay", "paypal"])
   .describe(
-    "PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2), `kakaopay`=카카오페이(직접 연동), `naverpay`=네이버페이 결제형(직접 연동)",
+    "PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2), `kakaopay`=카카오페이(직접 연동), `naverpay`=네이버페이 결제형(직접 연동), `paypal`=PayPal(직접 연동, 외화)",
   );
 export type PgProvider = z.infer<typeof pgProviderSchema>;
 
+/**
+ * 응답에 실리는 PG — 서버가 PG를 추가해도 응답 파싱이 깨지지 않게 문자열로 받는다(`easyPayProviderResponseSchema`와 같은 방식, 이슈 #131 CD2).
+ * 요청(우선순위·리포트 필터·경로)은 값을 골라 보내는 자리라 `pgProviderSchema` enum 그대로다. 현재 값은 `pgProviderSchema`의 값이고
+ * 화면은 모르는 값을 원문 그대로 보여 준다
+ */
+export const pgProviderResponseSchema = z
+  .string()
+  .describe("PG 식별자(`pgProviderSchema`의 값). 모르는 값이 와도 응답 파싱이 깨지지 않는다");
+
 /**
  * 간편결제 전용 PG — 결제수단이 간편결제 하나이고 간편결제사가 PG 자신이다(`kakaopay` → `KAKAOPAY`).
  * 이 PG는 `easyPayProviders` 설정 없이 결제 옵션이 하나(`EASY_PAY` + 그 간편결제사) 나온다
@@ -23,6 +32,7 @@ export type PgProvider = z.infer<typeof pgProviderSchema>;
 export const DEDICATED_EASY_PAY_PROVIDER = {
   kakaopay: "KAKAOPAY",
   naverpay: "NAVERPAY",
+  paypal: "PAYPAL",
 } as const satisfies Partial<Record<PgProvider, string>>;
 
 export const pgPaymentMethodSchema = z
@@ -34,7 +44,7 @@ export type PgPaymentMethod = z.infer<typeof pgPaymentMethodSchema>;
  * 간편결제사 — 결제 옵션(스토어프론트 `paymentOptions`)과 PG 설정의 `easyPayProviders`에 쓴다.
  * `@sayren/storefront-sdk`의 `easyPayProviderSchema`와 같은 값이다(api 계약 테스트가 고정한다)
  */
-export const easyPayProviderSchema = z.enum(["NAVERPAY", "KAKAOPAY", "TOSSPAY", "PAYCO"]);
+export const easyPayProviderSchema = z.enum(["NAVERPAY", "KAKAOPAY", "TOSSPAY", "PAYCO", "PAYPAL"]);
 export type EasyPayProvider = z.infer<typeof easyPayProviderSchema>;
 
 /**
@@ -188,6 +198,55 @@ export const naverPayCredentialsInputSchema = z.object({
 });
 export type NaverPayCredentialsInput = z.infer<typeof naverPayCredentialsInputSchema>;
 
+/**
+ * PayPal이 받는 통화 중 sayren이 여는 것(이슈 #131 설계 §3b) — PayPal 통화 코드(https://developer.paypal.com/api/rest/reference/currency-codes/) ∩ 통화표
+ * − 원화(PayPal이 받지 않는다) − CNY·MYR(현지 계정 전용) − TWD(부분 환불 소수 문제, 설계 Q4)
+ */
+export const PAYPAL_CURRENCIES = [
+  "USD",
+  "EUR",
+  "JPY",
+  "GBP",
+  "HKD",
+  "SGD",
+  "AUD",
+  "CAD",
+  "THB",
+  "PHP",
+  "NZD",
+  "CHF",
+] as const;
+
+export const payPalCredentialsInputSchema = z.object({
+  clientId: z
+    .string()
+    .trim()
+    .min(10)
+    .max(200)
+    .describe("PayPal REST 앱의 Client ID(테스트 세트는 샌드박스 앱). 공개 값"),
+  currencies: z
+    .array(z.enum(PAYPAL_CURRENCIES))
+    .min(1)
+    .max(PAYPAL_CURRENCIES.length)
+    .describe(
+      "받는 통화 — PayPal 계정에 열어 둔 통화를 고른다. 결제 세션 통화가 여기 있는 주문서에만 PayPal 옵션이 나온다(원화는 받지 않는다)",
+    ),
+  webhookId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(100)
+    .nullable()
+    .optional()
+    .describe(
+      "PayPal 앱에 등록한 웹훅의 ID(선택). 주면 서버 통지의 서명을 검증해 결제 확인을 앞당긴다. 생략·null이면 통지를 받지 않고 주기 확인만 한다",
+    ),
+  clientSecret: secretInput()
+    .optional()
+    .describe("Secret. 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+});
+export type PayPalCredentialsInput = z.infer<typeof payPalCredentialsInputSchema>;
+
 const upsertEnvironment = () =>
   pgEnvironmentSchema.describe(
     "저장할 자격 증명 세트. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 세트를 따로 둔다. " +
@@ -220,6 +279,12 @@ export const upsertNaverPayProviderRequestSchema = z.object({
 });
 export type UpsertNaverPayProviderRequest = z.infer<typeof upsertNaverPayProviderRequestSchema>;
 
+export const upsertPayPalProviderRequestSchema = z.object({
+  environment: upsertEnvironment(),
+  credentials: payPalCredentialsInputSchema,
+});
+export type UpsertPayPalProviderRequest = z.infer<typeof upsertPayPalProviderRequestSchema>;
+
 export const updatePaymentProviderRequestSchema = z
   .object({
     enabled: z
@@ -304,6 +369,11 @@ const publicConfigSchema = z.union([
   z.object({ storeId: z.string(), channels: z.array(portOneChannelSchema) }),
   z.object({ cid: z.string() }),
   z.object({ clientId: z.string(), chainId: z.string() }),
+  z.object({
+    clientId: z.string(),
+    currencies: z.array(z.string()),
+    webhookId: z.string().nullable(),
+  }),
 ]);
 
 const verificationSchema = z.object({
@@ -315,7 +385,7 @@ const verificationSchema = z.object({
 export const paymentCredentialSetSchema = z.object({
   environment: pgEnvironmentSchema,
   publicConfig: publicConfigSchema.describe(
-    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`, 카카오페이는 `{cid}`, 네이버페이는 `{clientId, chainId}`",
+    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`, 카카오페이는 `{cid}`, 네이버페이는 `{clientId, chainId}`, PayPal은 `{clientId, currencies, webhookId}`",
   ),
   secrets: z
     .array(maskedSecretSchema)
@@ -340,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>;
@@ -362,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({
@@ -371,7 +441,7 @@ export const liveGateErrorDetailsSchema = z.object({
 export type LiveGateErrorDetails = z.infer<typeof liveGateErrorDetailsSchema>;
 
 export const paymentProviderSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   displayName: z.string().describe("표시 이름 (토스페이먼츠·포트원)"),
   connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
   enabled: z.boolean().describe("결제에 사용 중인가"),
@@ -499,7 +569,7 @@ export const paymentSettingsSchema = z.object({
   providers: z
     .array(paymentProviderSchema)
     .describe(
-      "연결된 PG(우선순위순)와 연결되지 않은 토스페이먼츠·포트원. 카카오페이·네이버페이는 연결했을 때만 여기에 온다" +
+      "연결된 PG(우선순위순)와 연결되지 않은 토스페이먼츠·포트원. 그 밖의 PG(카카오페이·네이버페이 등)는 연결했을 때만 여기에 온다" +
         "(이 PG를 모르는 이전 SDK가 응답을 읽을 수 있게). 연결할 수 있는 PG 전체는 `connectableProviders`다",
     ),
   connectableProviders: z
@@ -539,7 +609,7 @@ export const paymentSettingsSchema = z.object({
 export type PaymentSettings = z.infer<typeof paymentSettingsSchema>;
 
 export const paymentProviderVerificationSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   environment: pgEnvironmentSchema.describe("연결 테스트한 자격 증명 세트"),
   result: pgVerificationResultSchema,
   message: z.string().nullable().describe("실패 사유 또는 참고 메시지"),
@@ -592,7 +662,7 @@ export type SalesTotals = z.infer<typeof salesTotalsSchema>;
 
 export const salesReportRowSchema = salesTotalsSchema.extend({
   date: z.string().nullable().describe("일자 (YYYY-MM-DD, Asia/Seoul). groupBy=DAY일 때만 값"),
-  provider: pgProviderSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
+  provider: pgProviderResponseSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
   method: pgPaymentMethodSchema
     .nullable()
     .describe(
@@ -602,17 +672,36 @@ export const salesReportRowSchema = salesTotalsSchema.extend({
 });
 export type SalesReportRow = z.infer<typeof salesReportRowSchema>;
 
+/** 통화별 매출(이슈 #130) — 환산하지 않는다. 금액은 그 통화의 최소 단위다 */
+export const salesReportCurrencySchema = z.object({
+  currency: z.string().describe("결제 통화(ISO 4217)"),
+  summary: salesTotalsSchema.describe("이 통화의 기간 전체 합계"),
+  rows: z.array(salesReportRowSchema).describe("이 통화의 집계 행(`groupBy` 기준)"),
+});
+export type SalesReportCurrency = z.infer<typeof salesReportCurrencySchema>;
+
 export const salesReportSchema = z.object({
   from: z.string(),
   to: z.string(),
   timezone: z.literal("Asia/Seoul"),
-  currency: z.literal("KRW"),
+  currency: z
+    .literal("KRW")
+    .describe(
+      "`summary`·`rows`의 통화. 기본 통화(원화) 결제만 집계한다. 외화 결제는 `byCurrency`에 있다",
+    ),
   groupBy: salesReportGroupBySchema,
-  provider: pgProviderSchema.nullable().describe("적용된 PG 필터"),
+  provider: pgProviderResponseSchema.nullable().describe("적용된 PG 필터"),
   method: pgPaymentMethodSchema.nullable().describe("적용된 결제수단 필터"),
   includeTest: z.boolean().describe("테스트 결제(샌드박스 결제)를 집계에 포함했는가"),
   summary: salesTotalsSchema.describe("기간 전체 합계"),
   rows: z.array(salesReportRowSchema).describe("집계 행. 활동이 없는 날짜·PG는 생략된다"),
+  byCurrency: z
+    .array(salesReportCurrencySchema)
+    .optional()
+    .default([])
+    .describe(
+      "통화별 매출(이슈 #130) — 활동이 있는 통화마다 한 항목이고 기본 통화(KRW)도 포함한다. 통화 사이는 환산하지 않는다. 옛 서버 응답은 빈 목록",
+    ),
 });
 export type SalesReport = z.infer<typeof salesReportSchema>;
 
@@ -677,7 +766,9 @@ export const cashReceiptSchema = z.object({
     .int()
     .describe("발급해야 할 금액 = 결제 금액 − 환불 완료 금액. 승인 전에는 결제 금액"),
   issuedAmount: z.number().int().describe("PG에 현재 발급돼 있는 금액. 취소됐거나 발급 전이면 0"),
-  provider: pgProviderSchema.nullable().describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
+  provider: pgProviderResponseSchema
+    .nullable()
+    .describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
   issueNumber: z.string().nullable().describe("현금영수증 승인 번호"),
   receiptUrl: z.string().nullable().describe("현금영수증 확인 주소"),
   issuedAt: z.string().nullable().describe("최근 발급 시각 (ISO 8601)"),
@@ -708,7 +799,9 @@ export const paymentRecordSchema = z.object({
     .describe(
       "환불 대기 금액 합계(#115) — 주문만 취소하고 아직 환불하지 않은 몫. 결제 상세에서 환불 처리한다",
     ),
-  provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
+  provider: pgProviderResponseSchema
+    .nullable()
+    .describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
   method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
   easyPayProvider: easyPayProviderResponseSchema
     .nullable()
@@ -764,7 +857,7 @@ export const paymentAttemptRecordSchema = z.object({
       "PG에 보낸 주문번호(이슈 #107) — 토스페이먼츠 orderId·포트원 paymentId. 새 시도는 `{주문번호}-{시도 순번 2자리}`이고, 번호 체계 이전 시도는 시도 id(`attemptId`)와 같습니다. PG 관리자 화면에서 결제를 찾을 때 씁니다",
     ),
   sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   status: paymentAttemptStatusSchema,
   method: pgPaymentMethodSchema.describe("주문서에서 고른 결제수단"),
   easyPayProvider: easyPayProviderResponseSchema
@@ -876,7 +969,7 @@ export type SetPlatformTestKeysRequest = z.infer<typeof setPlatformTestKeysReque
 
 /** 결제 상태 PG 한 줄 — 비밀 값·공개 키 없이 연결·사용·환경·테스트모드 키만 */
 export const paymentStatusProviderSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   displayName: z.string(),
   connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
   enabled: z.boolean().describe("결제에 사용 중인가"),

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>;