@sayren/storefront-sdk 0.15.0 → 0.17.0

package/src/schemas/order.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { easyPayProviderResponseSchema, paymentMethodSchema } from "./checkout";
 import { orderItemStatusSchema } from "./common";
 import { myOrderItemFulfillmentSnapshotSchema } from "./fulfillment";
+import { lineSelectionResponseShape } from "./product-options";
 
 export const myOrderItemSchema = z.object({
   orderItemId: z.string(),
@@ -9,6 +10,7 @@ export const myOrderItemSchema = z.object({
   productName: z.string(),
   thumbnailUrl: z.url().nullable().describe("주문 시점의 대표 이미지. 없었으면 null"),
   optionName: z.string().nullable(),
+  ...lineSelectionResponseShape,
   quantity: z.number().int().describe("주문 수량"),
   // 두 수량은 서버가 언제나 함께 싣는다. `store-sdk`의 `orderItemSchema`와 같은 규칙으로 **둘 다 필수**다 —
   // 응답 스키마는 OpenAPI 계약이기도 해서 기본값을 두면 선택 필드로 문서화되고, 필드가 빠진 응답이
@@ -32,57 +34,24 @@ export const myOrderItemSchema = z.object({
     ),
   status: orderItemStatusSchema,
   fulfillmentSnapshot: myOrderItemFulfillmentSnapshotSchema.describe(
-    "주문 시점 이행 스냅샷(이슈 #57). `type`이 주문 시점 상품 유형이다. 배송 상품이 아니면 `DELIVERED`는 제공 완료(방문 수령은 수령 완료)다. " +
-      "청약철회 제한 주문상품(`download`·`code`의 `withdrawalRestricted`)은 제공이 시작되면(다운로드·열람) 구매자 취소·반품을 받지 않는다",
+    "주문 시점 이행 스냅샷(이슈 #57). `type`이 주문 시점 상품 유형이다. 배송 없는 상품(`MANUAL`)이면 `DELIVERED`는 제공 완료다",
   ),
   fulfillment: z
     .object({
       status: z
         .string()
         .describe(
-          "제공 상태. `FULFILLED`(제공함)·`REVOKED`(환불 등으로 회수함). 값이 추가될 수 있어 문자열로 받는다",
+          "제공 상태. `FULFILLED`(제공함)·`REVOKED`(전량 취소·환불로 회수함). 값이 추가될 수 있어 문자열로 받는다",
         ),
       fulfilledAt: z.string().describe("제공 시각 (ISO 8601)"),
-      note: z.string().nullable().describe("셀러가 남긴 이용 안내. 없으면 null"),
-      codes: z
-        .array(
-          z.object({
-            codeId: z.string(),
-            hint: z.string().describe("가린 코드 — 끝 4자만 보인다(예: `****AB12`)"),
-            revealedAt: z.string().nullable().describe("처음 열람한 시각. 열람 전이면 null"),
-          }),
-        )
-        .optional()
-        .default([])
-        .describe(
-          "코드 발급 상품의 코드(가린 값). 평문은 `fulfillment/reveal`로 연다. 환불로 회수된 코드는 싣지 않는다. 서버는 항상 싣는다",
-        ),
-      download: z
-        .object({
-          count: z.number().int().describe("지금까지 받은 횟수"),
-          limit: z.number().int().describe("받을 수 있는 횟수"),
-          expiresAt: z.string().nullable().describe("받을 수 있는 기한 (ISO 8601)"),
-          files: z.array(
-            z.object({
-              assetId: z.string(),
-              fileName: z.string(),
-              sizeBytes: z.number().int().nullable(),
-            }),
-          ),
-        })
-        .nullable()
-        .optional()
-        .default(null)
-        .describe(
-          "파일 다운로드 상품의 횟수·기한·파일 목록. 파일 주소는 `downloads`로 받는다. 다른 유형은 null. 서버는 항상 싣는다",
-        ),
+      note: z.string().nullable().describe("판매자가 제공 처리 때 남긴 이용 안내. 없으면 null"),
     })
     .nullable()
     .optional()
     .default(null)
     .describe(
-      "비실물 상품(이용권·방문 수령 등)의 제공 정보(이슈 #48). 제공 전이거나 배송 상품이면 null이다. " +
-        "비실물의 `DELIVERED`는 제공 완료(방문 수령은 수령 완료)로 표시한다. 서버는 항상 싣는다",
+      "배송 없는 상품의 제공 기록(이슈 #48). 제공 전이거나 배송 상품이면 null이다. " +
+        "배송 없는 상품의 `DELIVERED`는 제공 완료로 표시한다. 서버는 항상 싣는다",
     ),
   claimStatus: z.string().nullable(),
   reviewWritten: z.boolean(),
@@ -165,14 +134,6 @@ export const myOrderSchema = z.object({
     paidAt: z.string().nullable(),
     receiptUrl: z.url().nullable(),
   }),
-  withdrawalAgreedAt: z
-    .string()
-    .nullable()
-    .optional()
-    .default(null)
-    .describe(
-      "청약철회 제한 안내에 동의한 시각(이슈 #48). 제한 상품이 없던 주문은 null. 서버는 항상 싣는다",
-    ),
   testPayment: z
     .boolean()
     .describe(
@@ -239,43 +200,3 @@ export const purchaseDecisionResultSchema = z.object({
 });
 
 export type PurchaseDecisionResult = z.infer<typeof purchaseDecisionResultSchema>;
-
-/**
- * 코드 열람 응답 (이슈 #48) — `POST /storefront/v1/me/order-items/{orderItemId}/fulfillment/reveal`(회원)·
- * `POST /storefront/v1/guest/orders/{orderId}/order-items/{orderItemId}/fulfillment/reveal`(비회원).
- * 평문 코드는 이 응답에만 있다. 화면에 보인 뒤 저장하지 않는다(응답은 `Cache-Control: no-store`).
- * 첫 열람 시각은 청약철회 판단의 근거(제공 개시)로 남는다.
- */
-export const fulfillmentRevealSchema = z.object({
-  orderItemId: z.string(),
-  codes: z.array(
-    z.object({
-      codeId: z.string(),
-      code: z.string().describe("코드 평문"),
-      revealedAt: z.string().describe("처음 열람한 시각"),
-    }),
-  ),
-});
-
-export type FulfillmentReveal = z.infer<typeof fulfillmentRevealSchema>;
-
-/**
- * 다운로드 요청 (이슈 #48) — `POST /storefront/v1/me/order-items/{orderItemId}/downloads`(회원)·
- * `POST /storefront/v1/guest/orders/{orderId}/order-items/{orderItemId}/downloads`(비회원, 연락처·비밀번호를 함께 보낸다).
- * 파일이 하나면 `assetId`를 생략할 수 있다.
- */
-export const downloadRequestSchema = z.object({
-  assetId: z.string().min(1).max(64).optional().describe("받을 파일. 파일이 여러 개면 필수다"),
-});
-
-export type DownloadRequest = z.infer<typeof downloadRequestSchema>;
-
-/** 다운로드 응답 — 수명 300초의 서명 주소. 받을 때마다 횟수가 하나 준다 */
-export const downloadLinkSchema = z.object({
-  url: z.url().describe("서명 주소. 300초 뒤 만료된다 — 받아서 바로 쓰고 저장하지 않는다"),
-  expiresAt: z.string().describe("서명 주소 만료 시각"),
-  fileName: z.string(),
-  remaining: z.number().int().describe("남은 다운로드 횟수"),
-});
-
-export type DownloadLink = z.infer<typeof downloadLinkSchema>;

package/src/schemas/product-options.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+
+/**
+ * 추가 선택·직접 입력 (이슈 #59) — 상품 상세의 옵션 표시, 장바구니 담기·바로 구매 요청, 줄 스냅샷의 공통 모양.
+ *
+ * 추가 선택은 재고가 없는 옵션이다. 구매자가 조합(옵션이 없으면 상품)을 고른 뒤 옵션명마다 값 하나를 더 고르고, 값의 추가금이
+ * 단가에 더해진다. 직접 입력은 구매자가 글자를 적는 항목(각인 문구 등)이다. 추가 선택 값이나 직접 입력값이 다르면 장바구니에서 다른 줄이다.
+ */
+
+export const addonGroupViewSchema = z.object({
+  groupId: z.string(),
+  name: z.string(),
+  required: z.boolean().describe("꼭 골라야 하는가. false면 고르지 않아도 된다(「선택 안 함」)"),
+  values: z
+    .array(
+      z.object({
+        valueId: z.string(),
+        name: z.string(),
+        additionalPrice: z.number().int().describe("이 값을 고르면 단가에 더하는 금액(원, 0 이상)"),
+      }),
+    )
+    .describe("고를 수 있는 값(셀러가 끈 값은 빠진다)"),
+});
+
+export type AddonGroupView = z.infer<typeof addonGroupViewSchema>;
+
+export const customInputViewSchema = z.object({
+  inputId: z.string(),
+  label: z.string().describe("항목명"),
+  placeholder: z.string().nullable().describe("입력 안내. 없으면 null"),
+  maxLength: z.number().int().describe("최대 글자 수"),
+  required: z.boolean(),
+});
+
+export type CustomInputView = z.infer<typeof customInputViewSchema>;
+
+/**
+ * 직접 입력값 정규화 — NFC로 모으고, 제어 문자(C0·C1·줄바꿈·줄·문단 구분자)는 공백으로, 제로폭·양방향 제어 문자는 지운 뒤
+ * 앞뒤 공백을 지운다. 서버가 저장하는 값이 이것이다. 빈 문자열이면 입력하지 않은 것으로 본다.
+ * (양방향 제어 문자를 두면 셀러 주문 화면의 각인 문구가 뒤집혀 보이게 할 수 있다.)
+ */
+export function normalizeCustomInputValue(value: string): string {
+  return (
+    value
+      .normalize("NFC")
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: 제어 문자를 지우려는 정규식이다
+      .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ")
+      .replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g, "")
+      .trim()
+  );
+}
+
+/**
+ * 직접 입력값의 글자 수 — 정규화한 값의 **코드 포인트 수**다(이모지 하나가 1자). 서버의 최대 글자 수 판정(`CUSTOM_INPUT_TOO_LONG`)과
+ * 스토어프론트·콘솔의 글자 수 표시가 이 함수 하나를 쓴다. `String.length`(UTF-16)로 세면 이모지가 2자로 세어 판정이 갈린다.
+ */
+export function customInputLength(value: string): number {
+  return [...normalizeCustomInputValue(value)].length;
+}
+
+/** 담기·바로 구매 요청의 직접 입력값 한 칸. 앞뒤 공백을 지우고, 빈 값은 입력하지 않은 것으로 본다 */
+export const customInputEntrySchema = z.object({
+  inputId: z.string(),
+  value: z.string().max(1000),
+});
+
+export type CustomInputEntry = z.infer<typeof customInputEntrySchema>;
+
+/** 고른 추가 선택 한 칸 — 옵션명(`groupId`)과 그 옵션명의 값(`valueId`) */
+export const addonSelectionSchema = z.object({
+  groupId: z.string(),
+  valueId: z.string(),
+});
+
+export type AddonSelection = z.infer<typeof addonSelectionSchema>;
+
+/** 요청의 추가 선택·직접 입력 필드 — 담기·장바구니 수정·바로 구매가 같은 이름을 쓴다 */
+export const lineSelectionRequestShape = {
+  addons: z
+    .array(addonSelectionSchema)
+    .max(20)
+    .optional()
+    .describe(
+      "고른 추가 선택(옵션명마다 하나, 고르지 않은 옵션명은 빼고 보낸다). 필수 옵션명을 빼면 400 `ADDON_OPTION_REQUIRED`, 없거나 꺼진 값이거나 한 옵션명에서 둘을 고르면 400 `ADDON_OPTION_NOT_FOUND`",
+    ),
+  customInputs: z
+    .array(customInputEntrySchema)
+    .max(20)
+    .optional()
+    .describe(
+      "직접 입력값. 필수 항목을 비우면 400 `CUSTOM_INPUT_REQUIRED`, 최대 글자 수를 넘으면 400 `CUSTOM_INPUT_TOO_LONG`, 없는 항목이면 400 `CUSTOM_INPUT_NOT_FOUND`",
+    ),
+};
+
+/** 줄의 옵션 선택 스냅샷 한 칸 — 조합 옵션은 옵션명마다 한 칸이고 추가금이 0이다(조합 추가금은 단가에 들어 있다) */
+export const optionSelectionViewSchema = z.object({
+  kind: z
+    .string()
+    .describe(
+      "옵션명 방식. 현재 값은 `combination`·`addon`이고 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  groupName: z.string(),
+  valueName: z.string(),
+  additionalPrice: z.number().int(),
+});
+
+export type OptionSelectionView = z.infer<typeof optionSelectionViewSchema>;
+
+export const customInputValueViewSchema = z.object({
+  label: z.string().describe("항목명"),
+  value: z.string().describe("구매자가 적은 값"),
+});
+
+export type CustomInputValueView = z.infer<typeof customInputValueViewSchema>;
+
+/** 응답 줄의 표시 필드 — 장바구니·주문서·주문상품이 같은 이름을 쓴다 */
+export const lineSelectionResponseShape = {
+  optionSelections: z
+    .array(optionSelectionViewSchema)
+    .optional()
+    .default([])
+    .describe("옵션 선택(조합 옵션 + 추가 선택). 옵션이 없으면 빈 배열. 서버는 항상 싣는다"),
+  customInputs: z
+    .array(customInputValueViewSchema)
+    .optional()
+    .default([])
+    .describe("직접 입력값(항목명과 값). 없으면 빈 배열. 서버는 항상 싣는다"),
+};