@sayren/store-sdk 0.20.0 → 0.22.0

package/package.json

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

package/src/client.ts

@@ -203,6 +203,15 @@ import {
   variantStockRequestSchema,
   variantStockSchema,
 } from "./schemas/product";
+import {
+  type SavedOptionSetFromProductRequestInput,
+  type SavedOptionSetListParams,
+  type SavedOptionSetRequestInput,
+  savedOptionSetFromProductRequestSchema,
+  savedOptionSetFromProductResultSchema,
+  savedOptionSetRequestSchema,
+  savedOptionSetSchema,
+} from "./schemas/saved-option-set";
 import {
   type AddressType,
   type Invitation,
@@ -221,6 +230,8 @@ import {
   updateStoreRequestSchema,
 } from "./schemas/store";
 import {
+  type AddStorefrontDomainRequest,
+  addStorefrontDomainRequestSchema,
   type ChangeStorefrontSlugRequest,
   type ChangeStorefrontTemplateRequest,
   type CreateStorefrontEditPreviewLinkRequest,
@@ -241,8 +252,10 @@ import {
   moveStorefrontFileRequestSchema,
   type PublishStorefrontVersionRequest,
   publishStorefrontVersionRequestSchema,
+  type ReplaceStorefrontSourceRequest,
   type RollbackStorefrontRequest,
   type RunStorefrontCheckRequest,
+  replaceStorefrontSourceRequestSchema,
   rollbackStorefrontRequestSchema,
   runStorefrontCheckRequestSchema,
   type SearchStorefrontFilesRequest,
@@ -260,12 +273,21 @@ import {
   storefrontFileWriteResultSchema,
   storefrontHostingSchema,
   storefrontPreviewLinkSchema,
+  storefrontSiteDomainSchema,
+  storefrontSiteDomainsSchema,
   storefrontSiteSchema,
   storefrontSlugAvailabilitySchema,
+  storefrontSourceArchivePartSchema,
+  storefrontSourceArchiveQuerySchema,
+  storefrontSourceBlobsResultSchema,
+  storefrontSourceReplacedSchema,
+  storefrontSourceSchema,
   storefrontTemplateSchema,
   storefrontVerifyReportSchema,
   storefrontVersionCreatedSchema,
   storefrontVersionSchema,
+  type UploadStorefrontSourceBlobsRequest,
+  uploadStorefrontSourceBlobsRequestSchema,
   type WriteStorefrontFilesRequest,
   writeStorefrontFilesRequestSchema,
 } from "./schemas/storefront-hosting";
@@ -571,6 +593,39 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("DELETE", path`/products/${productId}/discount`),
     },
 
+    /**
+     * 저장 옵션 (이슈 #59) — 자주 쓰는 옵션 구성. 불러오기는 복사라 저장 옵션을 고쳐도 불러온 상품은 바뀌지 않는다.
+     * 권한은 상품과 같다(`product:r`·`product:rw`).
+     */
+    savedOptionSets: {
+      list: (params?: SavedOptionSetListParams) =>
+        storeHttp.request("GET", "/saved-option-sets", pageSchema(savedOptionSetSchema), {
+          query: params as Query,
+        }),
+      get: (optionSetId: string) =>
+        storeHttp.request("GET", path`/saved-option-sets/${optionSetId}`, savedOptionSetSchema),
+      /** 이름이 겹치면 409 `OPTION_SET_NAME_TAKEN`, 스토어당 200개를 넘으면 409 `OPTION_SET_LIMIT_EXCEEDED` */
+      create: (body: SavedOptionSetRequestInput) =>
+        storeHttp.request("POST", "/saved-option-sets", savedOptionSetSchema, {
+          body: savedOptionSetRequestSchema.parse(body),
+        }),
+      /** 통째로 바꾼다. 불러온 상품은 바뀌지 않는다 */
+      update: (optionSetId: string, body: SavedOptionSetRequestInput) =>
+        storeHttp.request("PUT", path`/saved-option-sets/${optionSetId}`, savedOptionSetSchema, {
+          body: savedOptionSetRequestSchema.parse(body),
+        }),
+      remove: (optionSetId: string) =>
+        storeHttp.requestVoid("DELETE", path`/saved-option-sets/${optionSetId}`),
+      /** 상품의 현재 옵션을 저장 옵션으로 만든다(또는 `replaceOptionSetId`를 덮어쓴다) */
+      saveFromProduct: (body: SavedOptionSetFromProductRequestInput) =>
+        storeHttp.request(
+          "POST",
+          "/saved-option-sets/from-product",
+          savedOptionSetFromProductResultSchema,
+          { body: savedOptionSetFromProductRequestSchema.parse(body) },
+        ),
+    },
+
     categories: {
       list: (params?: { parentId?: string; flat?: boolean }) =>
         storeHttp.request("GET", "/categories", z.array(categorySchema), {
@@ -1347,6 +1402,34 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("POST", "/storefront/site/preview-link", storefrontPreviewLinkSchema, {
           body: createStorefrontPreviewLinkRequestSchema.parse(body),
         }),
+      /** `GET /v1/storefront/site/domains` — 주소 목록(기본 주소 + 내 도메인)과 DNS 안내 */
+      listDomains: () =>
+        storeHttp.request("GET", "/storefront/site/domains", storefrontSiteDomainsSchema),
+      /**
+       * `POST /v1/storefront/site/domains` (201) — 내 도메인을 추가한다. 응답의 `dnsRecords`를 DNS에 넣으면 서버가 소유를 확인하고
+       * 인증서를 발급한다
+       */
+      addDomain: (body: AddStorefrontDomainRequest) =>
+        storeHttp.request("POST", "/storefront/site/domains", storefrontSiteDomainSchema, {
+          body: addStorefrontDomainRequestSchema.parse(body),
+        }),
+      /** `POST /v1/storefront/site/domains/{domainId}/verify` — DNS를 곧바로 다시 확인한다(실패한 도메인은 처음부터 다시) */
+      verifyDomain: (domainId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/storefront/site/domains/${domainId}/verify`,
+          storefrontSiteDomainSchema,
+        ),
+      /** `POST /v1/storefront/site/domains/{domainId}/primary` — 대표 주소로 지정한다. 다른 주소는 대표 주소로 301한다 */
+      setPrimaryDomain: (domainId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/storefront/site/domains/${domainId}/primary`,
+          storefrontSiteDomainsSchema,
+        ),
+      /** `DELETE /v1/storefront/site/domains/{domainId}` — 내 도메인 연결을 해제한다(곧바로 끊긴다) */
+      removeDomain: (domainId: string) =>
+        storeHttp.requestVoid("DELETE", path`/storefront/site/domains/${domainId}`),
       /** `POST /v1/storefront/site/disable` — 호스팅을 끈다(사이트 `CLOSED`, 슬러그 90일 보류). 다시 만들 수 있다 */
       disable: (body: DisableStorefrontHostingRequest) =>
         storeHttp.request("POST", "/storefront/site/disable", storefrontSiteSchema, {
@@ -1453,6 +1536,35 @@ export function createStoreClient(options: StoreClientOptions) {
       /** `GET /v1/storefront/site/builds/{buildId}` — 빌드 상태·실패 단계·로그 꼬리·규칙 결과 */
       getBuild: (buildId: string) =>
         storeHttp.request("GET", path`/storefront/site/builds/${buildId}`, storefrontBuildSchema),
+
+      // ─── 소스 내려받기·올리기 (#60, `sayren` CLI) ───
+
+      /** `GET /v1/storefront/site/source` — 지금 작업 트리를 고정하고 압축 파일(tar.gz) 크기·조각 수를 알린다 */
+      getSource: () => storeHttp.request("GET", "/storefront/site/source", storefrontSourceSchema),
+      /** `GET /v1/storefront/site/source/archive?sourceRef=&part=` — 압축 파일 조각(base64, 4MiB까지) */
+      getSourceArchive: (params: { sourceRef: string; part?: number }) =>
+        storeHttp.request(
+          "GET",
+          "/storefront/site/source/archive",
+          storefrontSourceArchivePartSchema,
+          { query: storefrontSourceArchiveQuerySchema.parse(params) as Query },
+        ),
+      /** `POST /v1/storefront/site/source/blobs` — 파일 내용 올리기(해시 키). 작업 트리는 바뀌지 않는다 */
+      uploadSourceBlobs: (body: UploadStorefrontSourceBlobsRequest) =>
+        storeHttp.request(
+          "POST",
+          "/storefront/site/source/blobs",
+          storefrontSourceBlobsResultSchema,
+          { body: uploadStorefrontSourceBlobsRequestSchema.parse(body) },
+        ),
+      /**
+       * `PUT /v1/storefront/site/source` — 작업 트리 전체를 바꾼다. 409 `SOURCE_CHANGED`(내려받은 뒤 바뀜)·`EDIT_SESSION_OPEN`·
+       * `SOURCE_BLOBS_MISSING`(`details.hashes`를 올리고 다시)
+       */
+      replaceSource: (body: ReplaceStorefrontSourceRequest) =>
+        storeHttp.request("PUT", "/storefront/site/source", storefrontSourceReplacedSchema, {
+          body: replaceStorefrontSourceRequestSchema.parse(body),
+        }),
     },
 
     store: {

package/src/index.ts

@@ -35,6 +35,7 @@ export * from "./schemas/payment";
 export * from "./schemas/product";
 export * from "./schemas/promotion";
 export * from "./schemas/refund-policy";
+export * from "./schemas/saved-option-set";
 export * from "./schemas/scope";
 export * from "./schemas/shipping-policy";
 export * from "./schemas/store";

package/src/schemas/order.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
 import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
 import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
+import { customInputValueSchema, optionSelectionSchema } from "./product";
 
 export const orderSummarySchema = z.object({
   orderId: z.string(),
@@ -59,6 +60,20 @@ export const orderItemSchema = z.object({
   productName: z.string(),
   optionId: z.string().nullable(),
   optionName: z.string().nullable(),
+  optionSelections: z
+    .array(optionSelectionSchema)
+    .optional()
+    .default([])
+    .describe(
+      "주문 시점 옵션 선택(이슈 #59) — 조합 옵션(옵션명마다 한 칸, 추가금 0)과 추가 선택(값의 추가금). 옵션이 없거나 이 필드 이전 주문은 빈 배열. 서버는 항상 싣는다",
+    ),
+  customInputs: z
+    .array(customInputValueSchema)
+    .optional()
+    .default([])
+    .describe(
+      "구매자가 적은 직접 입력값(주문 시점 항목명과 값, 이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다",
+    ),
   sellerCode: z.string().nullable(),
   fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema.describe(
     "주문 시점 이행 스냅샷(이슈 #57). `type`이 주문 시점 상품 유형이다. 배송 상품이 아니면 발송·배송완료 대신 제공 처리를 하고, " +

package/src/schemas/product.ts

@@ -76,10 +76,188 @@ export const productVariantSchema = z.object({
   weightGram: z.number().int().nullable(),
   sellerCode: z.string().nullable(),
   usable: z.boolean(),
+  hasOrders: z
+    .boolean()
+    .optional()
+    .describe(
+      "주문에 담긴 적이 있는 조합인가(이슈 #59). true인 조합은 옵션 교체에서 뺄 수 없고(409 `OPTION_HAS_ORDERS`) `usable: false`로 판매를 끈다. 서버는 항상 싣는다. 요청에는 쓰지 않는다",
+    ),
 });
 
 export type ProductVariant = z.infer<typeof productVariantSchema>;
 
+/** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
+export const MAX_OPTION_GROUPS = 3;
+/** 축 하나가 가질 수 있는 값의 최대 개수 */
+export const MAX_VALUES_PER_GROUP = 100;
+/** 상품 하나가 가질 수 있는 variant(SKU) 최대 개수 */
+export const MAX_VARIANTS = 500;
+
+// ─── 추가 선택 옵션·직접 입력 항목 (이슈 #59) ─────────────────────
+//
+// 옵션명은 두 방식이다. **조합**(`optionGroups`)은 값의 조합이 판매 단위(variant)가 되고 재고·SKU·추가금이 조합에 붙는다.
+// **추가 선택**(`addonGroups`)은 재고가 없고 값마다 추가금만 있다 — 구매자가 조합(옵션이 없으면 기본 판매 단위)을 고른 뒤
+// 옵션명마다 값 하나를 더 고르고, 재고는 고른 조합에서 빠진다. 직접 입력 항목(`customInputs`)은 구매자가 글자를 적는 칸이다.
+
+/** 추가 선택 옵션명 최대 개수 */
+export const MAX_ADDON_GROUPS = 5;
+/** 직접 입력 항목 최대 개수 */
+export const MAX_CUSTOM_INPUTS = 5;
+/** 직접 입력 항목 최대 글자 수의 상한 */
+export const MAX_CUSTOM_INPUT_LENGTH = 200;
+/** 조합 수가 이 값 이상이면 콘솔이 경고한다(상한은 `MAX_VARIANTS`) */
+export const VARIANT_COUNT_WARNING = 100;
+
+/**
+ * 옵션 값 정렬 순서 — 등록순·가나다순·낮은 추가금순·높은 추가금순. 서버가 저장할 때 이 순서로 값의 `sortOrder`를 매긴다.
+ * 추가금순은 추가 선택 값이면 값의 추가금, 조합 값이면 그 값이 든 조합 추가금의 최솟값으로 비교하고 같으면 등록순이다.
+ */
+export const optionSortSchema = z.enum(["REGISTERED", "NAME", "PRICE_ASC", "PRICE_DESC"]);
+
+export type OptionSort = z.infer<typeof optionSortSchema>;
+
+/** 추가 선택 값 — 예: 옵션명 "선물 포장"의 값 "포장함"(+2,000원) */
+export const addonValueSchema = z.object({
+  valueId: z.string(),
+  name: z.string(),
+  sortOrder: z.number().int(),
+  additionalPrice: z.number().int().describe("이 값을 고르면 단가에 더하는 금액(원, 0 이상)"),
+  usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않고 고를 수 없다"),
+});
+
+export type AddonValue = z.infer<typeof addonValueSchema>;
+
+/** 추가 선택 옵션명 */
+export const addonGroupSchema = z.object({
+  groupId: z.string(),
+  name: z.string(),
+  sortOrder: z.number().int(),
+  required: z.boolean().describe("구매자가 꼭 골라야 하는가. false면 고르지 않아도 된다"),
+  values: z.array(addonValueSchema),
+});
+
+export type AddonGroup = z.infer<typeof addonGroupSchema>;
+
+/** 직접 입력 항목 — 예: 각인 문구 */
+export const customInputSchema = z.object({
+  inputId: z.string(),
+  label: z.string().describe("항목명"),
+  placeholder: z.string().nullable().describe("입력 안내(구매자 입력 칸의 안내 문구). 없으면 null"),
+  maxLength: z.number().int().describe("최대 글자 수"),
+  required: z.boolean(),
+  usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않는다"),
+  sortOrder: z.number().int(),
+});
+
+export type CustomInput = z.infer<typeof customInputSchema>;
+
+/**
+ * 직접 입력 항목명에 쓸 수 없는 개인정보성 단어 — 콘솔 검사와 서버 400(`CUSTOM_INPUT_LABEL_FORBIDDEN`)이 이 목록 하나를 쓴다.
+ * 구매자 개인정보는 주문 정보로 받는다. 직접 입력 항목으로 받으면 보관·파기 규칙 밖에 남는다.
+ */
+export const CUSTOM_INPUT_FORBIDDEN_WORDS = [
+  "연락처",
+  "전화",
+  "휴대폰",
+  "핸드폰",
+  "폰번호",
+  "메일",
+  "주소",
+  "주민",
+  "생년월일",
+  "생일",
+  "실명",
+  "계좌",
+  "카드번호",
+  "비밀번호",
+  "여권",
+  "통관",
+  "phone",
+  "mobile",
+  "mail",
+  "address",
+] as const;
+
+/** 금지어 비교용 정규화 — NFKC(전각·호환 문자를 보통 문자로)·소문자 뒤 문자·숫자만 남긴다(공백·기호·제로폭 문자로 쪼갠 우회를 막는다) */
+function forbiddenWordKeyOf(text: string): string {
+  return text
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]/gu, "");
+}
+
+/**
+ * 직접 입력 항목명·입력 안내에 든 개인정보성 금지어. 없으면 null. 공백·기호·대소문자·전각을 무시한다.
+ * 서버는 항목명과 입력 안내 둘 다 이 함수로 검사한다(안내에 「연락처를 적어 주십시오」라고 쓰는 우회를 막는다).
+ */
+export function customInputLabelForbiddenWord(label: string): string | null {
+  const normalized = forbiddenWordKeyOf(label);
+  return (
+    CUSTOM_INPUT_FORBIDDEN_WORDS.find((word) => normalized.includes(forbiddenWordKeyOf(word))) ??
+    null
+  );
+}
+
+/** 옵션명·값 이름 — 앞뒤 공백을 지우고 빈 값은 받지 않는다 */
+const optionNameSchema = z.string().trim().min(1).max(50);
+
+export const addonValueRequestSchema = z.object({
+  /** 전달 시 기존 값 행을 유지(UPDATE). 생략하면 신규 발급 */
+  valueId: z.string().optional(),
+  name: optionNameSchema,
+  additionalPrice: z.number().int().min(0).default(0).describe("추가금(원, 0 이상)"),
+  usable: z.boolean().default(true),
+});
+
+export type AddonValueRequest = z.infer<typeof addonValueRequestSchema>;
+
+export const addonGroupRequestSchema = z.object({
+  /** 전달 시 기존 옵션명 행을 유지(UPDATE). 조합 옵션명의 id는 줄 수 없다(방식을 바꾸려면 새 옵션명으로 보낸다) */
+  groupId: z.string().optional(),
+  name: optionNameSchema,
+  required: z.boolean().default(false),
+  values: z.array(addonValueRequestSchema).min(1).max(MAX_VALUES_PER_GROUP),
+});
+
+export type AddonGroupRequest = z.infer<typeof addonGroupRequestSchema>;
+
+export const customInputRequestSchema = z.object({
+  /** 전달 시 기존 항목 행을 유지(UPDATE). 생략하면 신규 발급 */
+  inputId: z.string().optional(),
+  label: z.string().trim().min(1).max(30),
+  placeholder: z.string().trim().max(100).nullish(),
+  maxLength: z.number().int().min(1).max(MAX_CUSTOM_INPUT_LENGTH),
+  required: z.boolean().default(false),
+  usable: z.boolean().default(true),
+});
+
+export type CustomInputRequest = z.infer<typeof customInputRequestSchema>;
+
+/**
+ * 주문상품·장바구니·주문서 줄의 옵션 선택 스냅샷 한 칸 — 주문 시점 이름이다(상품을 고쳐도 바뀌지 않는다).
+ * 조합 옵션은 옵션명마다 한 칸이고 추가금은 조합 단위라 0이다(조합 추가금은 단가에 들어 있다). 추가 선택은 값의 추가금이다.
+ */
+export const optionSelectionSchema = z.object({
+  kind: z
+    .string()
+    .describe(
+      "옵션명 방식. 현재 값은 `combination`·`addon`이고 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  groupName: z.string(),
+  valueName: z.string(),
+  additionalPrice: z.number().int(),
+});
+
+export type OptionSelection = z.infer<typeof optionSelectionSchema>;
+
+/** 구매자가 적은 직접 입력값 — 주문 시점 항목명과 값 */
+export const customInputValueSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+});
+
+export type CustomInputValue = z.infer<typeof customInputValueSchema>;
+
 export const discountSchema = z.object({
   productId: z.string(),
   discountType: z.enum(["RATE", "AMOUNT"]),
@@ -104,6 +282,22 @@ export const productSchema = productSummarySchema.extend({
   optionGroups: z.array(optionGroupSchema),
   /** 모든 상품이 최소 1개 variant를 갖는다 (옵션 없으면 default variant 1개) */
   variants: z.array(productVariantSchema),
+  addonGroups: z
+    .array(addonGroupSchema)
+    .optional()
+    .default([])
+    .describe("추가 선택 옵션명(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
+  customInputs: z
+    .array(customInputSchema)
+    .optional()
+    .default([])
+    .describe(
+      "직접 입력 항목(이슈 #59). 사용하지 않는 항목도 싣는다. 없으면 빈 배열. 서버는 항상 싣는다",
+    ),
+  optionSort: optionSortSchema
+    .optional()
+    .default("REGISTERED")
+    .describe("옵션 값 정렬 순서(이슈 #59). 서버는 항상 싣는다"),
   fulfillment: productFulfillmentResponseSchema,
   fulfillmentTypeLocked: z
     .boolean()
@@ -187,13 +381,6 @@ export function productImageRejection(url: string): ProductImageRejection | null
   return null;
 }
 
-/** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
-export const MAX_OPTION_GROUPS = 3;
-/** 축 하나가 가질 수 있는 값의 최대 개수 */
-export const MAX_VALUES_PER_GROUP = 100;
-/** 상품 하나가 가질 수 있는 variant(SKU) 최대 개수 */
-export const MAX_VARIANTS = 500;
-
 /**
  * 식별 코드 — 빈 문자열·공백만 있는 값은 거부한다.
  * `""`를 통과시키면 서버 중복 사전 검사(falsy skip)와 DB partial unique
@@ -244,6 +431,25 @@ export type ProductVariantRequest = z.infer<typeof productVariantRequestSchema>;
 export const optionModelRequestSchema = z.object({
   optionGroups: z.array(optionGroupRequestSchema).max(MAX_OPTION_GROUPS).default([]),
   variants: z.array(productVariantRequestSchema).min(1).max(MAX_VARIANTS),
+  addonGroups: z
+    .array(addonGroupRequestSchema)
+    .max(MAX_ADDON_GROUPS)
+    .optional()
+    .describe(
+      "추가 선택 옵션명 전체(이슈 #59). 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 끄려면 빈 배열을 보낸다. 기능이 열리기 전에는 비어 있지 않은 값이 409 `OPTION_ADDONS_UNAVAILABLE`이다",
+    ),
+  customInputs: z
+    .array(customInputRequestSchema)
+    .max(MAX_CUSTOM_INPUTS)
+    .optional()
+    .describe(
+      "직접 입력 항목 전체(이슈 #59). 배열 순서가 표시 순서다. 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 항목명에 개인정보성 단어(`CUSTOM_INPUT_FORBIDDEN_WORDS`)가 있으면 400 `CUSTOM_INPUT_LABEL_FORBIDDEN`, 기능이 열리기 전에는 비어 있지 않은 값이 409 `OPTION_ADDONS_UNAVAILABLE`이다",
+    ),
+  optionSort: optionSortSchema
+    .optional()
+    .describe(
+      "옵션 값 정렬 순서(이슈 #59). 서버가 이 순서로 값의 `sortOrder`를 다시 매긴다. 생략하면 등록은 `REGISTERED`, 수정은 현재 값이다",
+    ),
 });
 
 export type OptionModelRequest = z.infer<typeof optionModelRequestSchema>;
@@ -252,6 +458,20 @@ export type OptionModelRequest = z.infer<typeof optionModelRequestSchema>;
 export const optionModelSchema = z.object({
   optionGroups: z.array(optionGroupSchema),
   variants: z.array(productVariantSchema),
+  addonGroups: z
+    .array(addonGroupSchema)
+    .optional()
+    .default([])
+    .describe("추가 선택 옵션명(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
+  customInputs: z
+    .array(customInputSchema)
+    .optional()
+    .default([])
+    .describe("직접 입력 항목(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
+  optionSort: optionSortSchema
+    .optional()
+    .default("REGISTERED")
+    .describe("옵션 값 정렬 순서(이슈 #59). 서버는 항상 싣는다"),
 });
 
 export type OptionModel = z.infer<typeof optionModelSchema>;
@@ -322,6 +542,13 @@ const productWriteShape = {
         "반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 줄 수 있다(다른 유형은 400)",
     ),
   ...optionModelRequestSchema.shape,
+  sourceOptionSetIds: z
+    .array(z.string())
+    .max(10)
+    .optional()
+    .describe(
+      "쓰기 전용(이슈 #59) — 이 저장으로 옵션을 불러온 저장 옵션 id. 상품 저장과 같은 트랜잭션에서 불러오기 기록을 남겨 저장 옵션의 `importedProductCount`를 센다. 없는 id는 무시한다",
+    ),
 };
 
 export const productCreateRequestSchema = z.strictObject({

package/src/schemas/promotion.ts

@@ -158,6 +158,7 @@ export const couponRejectReasonSchema = z
     "NO_ELIGIBLE_ITEMS",
     "MIN_ORDER_AMOUNT",
     "LINE_NOT_ELIGIBLE",
+    "LINE_AMBIGUOUS",
     "NO_DISCOUNT",
   ])
   .describe(
@@ -165,7 +166,8 @@ export const couponRejectReasonSchema = z
       "`STACK_LIMIT`=같은 종류의 쿠폰이 이미 적용됨(주문 쿠폰·배송비 쿠폰은 주문당 1장, 상품 쿠폰은 주문상품 한 줄에 1장), " +
       "`NOT_STARTED`=사용 기간 전, `EXPIRED`=사용 기간 지남, `MEMBER_ONLY`=회원 전용, `FIRST_ORDER_ONLY`=첫 구매 전용, " +
       "`NO_ELIGIBLE_ITEMS`=대상 상품이 주문에 없음, `MIN_ORDER_AMOUNT`=최소 주문 금액 미달, " +
-      "`LINE_NOT_ELIGIBLE`=지정한 주문상품이 대상이 아니거나 이미 상품 쿠폰이 있음, `NO_DISCOUNT`=할인할 금액이 없음",
+      "`LINE_NOT_ELIGIBLE`=지정한 주문상품이 대상이 아니거나 이미 상품 쿠폰이 있음, " +
+      "`LINE_AMBIGUOUS`=지정한 `optionId`의 줄이 여럿이라 줄을 정할 수 없음(`lineId`로 지목한다), `NO_DISCOUNT`=할인할 금액이 없음",
   );
 export type CouponRejectReason = z.infer<typeof couponRejectReasonSchema>;