@sayren/storefront-sdk 0.6.0 → 0.8.0

package/src/schemas/checkout.ts

@@ -37,6 +37,11 @@ export const checkoutSessionSchema = z.object({
     totalAmount: z.number().int(),
   }),
   expiresAt: z.string(),
+  paymentOptions: z
+    .lazy(() => paymentOptionListSchema)
+    .describe(
+      "이 주문서에서 고를 수 있는 결제 옵션, PG 우선순위순. 셀러가 켠 PG·결제수단·간편결제만 담긴다. 비어 있으면 지금 결제할 수 없다",
+    ),
   testPayment: z
     .boolean()
     .describe(
@@ -56,6 +61,70 @@ export const paymentMethodSchema = z.enum([
 
 export type PaymentMethod = z.infer<typeof paymentMethodSchema>;
 
+/** 결제를 처리하는 PG. 셀러가 직접 계약하고 콘솔 설정 › 결제에서 연결한다 */
+export const pgProviderSchema = z.enum(["tosspayments", "portone"]);
+export type PgProvider = z.infer<typeof pgProviderSchema>;
+
+/** 간편결제사. 토스페이먼츠·포트원 모두 같은 코드를 쓴다 */
+export const easyPayProviderSchema = z.enum(["NAVERPAY", "KAKAOPAY", "TOSSPAY", "PAYCO"]);
+export type EasyPayProvider = z.infer<typeof easyPayProviderSchema>;
+
+/**
+ * 응답에 실리는 간편결제사 — 서버가 간편결제사를 추가해도 파싱이 깨지지 않게 문자열로 받는다
+ * (`pgProvider`·결제 상태와 같은 방식). 요청과 결제 옵션은 값을 골라 보내는 자리라 enum 그대로다.
+ */
+export const easyPayProviderResponseSchema = z.string();
+
+const pg = pgProviderSchema.describe("결제를 처리할 PG");
+
+/**
+ * 결제 옵션 — 어느 PG로 어떤 결제수단을 쓸지. `method`로 좁히면 필요한 필드가 타입으로 정해진다
+ * (`EASY_PAY`만 `provider`가 있다). 주문서의 `paymentOptions` 항목을 그대로 넘기거나 직접 써도 된다.
+ * 셀러가 켜지 않은 조합이면 서버가 409 `PAYMENT_OPTION_UNAVAILABLE`로 거절한다.
+ */
+export const paymentOptionSchema = z.discriminatedUnion("method", [
+  z.object({ pg, method: z.literal("CARD") }),
+  z.object({
+    pg,
+    method: z.literal("EASY_PAY"),
+    provider: easyPayProviderSchema.describe("간편결제사 — 이 간편결제 결제창을 바로 연다"),
+  }),
+  z.object({ pg, method: z.literal("BANK_TRANSFER") }),
+  z.object({ pg, method: z.literal("VIRTUAL_ACCOUNT") }),
+  z.object({ pg, method: z.literal("MOBILE") }),
+]);
+export type PaymentOption = z.infer<typeof paymentOptionSchema>;
+
+/** 주문서가 내려주는 결제 옵션 — 결제 옵션 + 표시 이름 */
+export const availablePaymentOptionSchema = paymentOptionSchema.and(
+  z.object({
+    label: z.string().describe("결제수단 표시 이름 (예: 신용·체크카드, 네이버페이)"),
+    pgName: z.string().describe("PG 표시 이름 (예: 토스페이먼츠)"),
+  }),
+);
+export type AvailablePaymentOption = z.infer<typeof availablePaymentOptionSchema>;
+
+/**
+ * 결제 옵션 목록 — 서버가 나중에 추가한 결제수단·PG를 이 SDK가 모르면 **그 항목만 빼고** 읽는다(목록 파싱은 깨지지 않는다).
+ *
+ * 모르는 항목을 버리는 일은 `preprocess`가 하고 항목 타입은 그대로 남는다 — OpenAPI 문서에 `items` 없는
+ * 배열로 나가지 않게 하기 위해서다(`z.array(z.unknown()).transform(...)`은 출력 타입을 표현하지 못한다).
+ */
+export const paymentOptionListSchema = z.preprocess(
+  (value) =>
+    Array.isArray(value)
+      ? value.filter((item) => availablePaymentOptionSchema.safeParse(item).success)
+      : value,
+  z.array(availablePaymentOptionSchema),
+);
+
+/** 결제 옵션을 화면 키로 — 라디오 value·React key. 예: `tosspayments:CARD`, `portone:EASY_PAY:NAVERPAY` */
+export function paymentOptionKey(option: PaymentOption): string {
+  return option.method === "EASY_PAY"
+    ? `${option.pg}:EASY_PAY:${option.provider}`
+    : `${option.pg}:${option.method}`;
+}
+
 export const shippingAddressInputSchema = z.object({
   addressId: z.string().optional(),
   receiverName: z.string().min(1, "수령인명을 입력해주세요").max(50),
@@ -78,51 +147,43 @@ export const guestInfoSchema = z.object({
 
 export type GuestInfo = z.infer<typeof guestInfoSchema>;
 
-export const requestPaymentRequestSchema = z.object({
+/**
+ * 결제 시작 — 배송지를 확정하고 고른 결제 옵션으로 결제 시도를 연다. 응답의 `payUrl`(결제 서비스)을 팝업(`mode=popup`)이나
+ * 전체 페이지로 열면 결제 서비스가 PG 결제창을 띄우고 승인까지 한다. 리다이렉트 결제가 끝나면 구매자는 `returnUrl`로 돌아온다.
+ * `returnUrl`의 도메인은 스토어 결제 도메인(콘솔 설정 › 결제)에 등록돼 있어야 한다(테스트 결제는 localhost 허용).
+ */
+export const startPaymentRequestSchema = z.object({
+  option: paymentOptionSchema,
+  returnUrl: z
+    .url()
+    .max(2048)
+    .describe(
+      "결제를 마치면 돌아올 스토어프론트 주소. 스토어 결제 도메인에 등록된 도메인이어야 한다",
+    ),
   shippingAddress: shippingAddressInputSchema,
-  paymentMethod: paymentMethodSchema,
   guest: guestInfoSchema.optional(),
 });
 
-export type RequestPaymentRequest = z.infer<typeof requestPaymentRequestSchema>;
+export type StartPaymentRequest = z.infer<typeof startPaymentRequestSchema>;
 
-/**
- * 결제창 파라미터. 스토어프론트가 쓰는 계약 값은 `popupUrl` 하나다(결제 팝업을 연다).
- *
- * 나머지는 결제 팝업 내부 값이라 선택 필드로만 타입을 준다(`attemptId`·`provider`·`mock`, 그리고
- * 토스 `clientKey`·`orderId`…, 포트원 `storeId`·`channelKey`… 같은 PG별 결제창 값). 공개 값뿐이며
- * 시크릿은 어떤 키에도 없다. 서버가 키를 추가·변경해도 파싱이 깨지지 않도록 모르는 키는 그대로 통과시킨다.
- */
-export const pgParamsSchema = z.looseObject({
-  popupUrl: z.string().describe("결제 팝업 진입 URL. `window.open`으로 띄운다"),
-  attemptId: z
-    .string()
-    .optional()
-    .describe(
-      "첫 결제 시도 id(`att_…`). PG에 보내는 주문번호(토스 `orderId`, 포트원 `paymentId`)다. 팝업 내부 값",
-    ),
-  provider: z.string().optional().describe("첫 결제 시도의 PG (`pgProvider`와 같다). 팝업 내부 값"),
-  mock: z
-    .boolean()
-    .optional()
-    .describe("모의 결제 여부. true면 결제 팝업이 PG SDK 대신 모의 결제 UI를 띄운다. 팝업 내부 값"),
-  environment: z
-    .string()
-    .optional()
-    .describe("첫 결제 시도의 결제 환경 (`TEST` 샌드박스 · `LIVE` 실결제). 팝업 내부 값"),
+/** 같은 결제에서 다른 결제 옵션으로 다시 시도. `returnUrl`을 생략하면 결제 시작 때의 복귀 주소를 쓴다 */
+export const retryPaymentRequestSchema = z.object({
+  option: paymentOptionSchema,
+  returnUrl: startPaymentRequestSchema.shape.returnUrl.optional(),
 });
 
-export type PgParams = z.infer<typeof pgParamsSchema>;
+export type RetryPaymentRequest = z.infer<typeof retryPaymentRequestSchema>;
 
-export const paymentParamsSchema = z.object({
-  paymentId: z.string(),
-  pgProvider: z
+export const paymentStartSchema = z.object({
+  paymentId: z.string().describe("결제 id. 상태 조회·재시도의 키다"),
+  attemptId: z.string().describe("결제 시도 id. PG 주문번호(토스 orderId, 포트원 paymentId)다"),
+  option: paymentOptionSchema.describe("이 시도의 결제 옵션"),
+  payUrl: z
     .string()
     .describe(
-      "첫 결제 시도의 PG. 현재 값은 `tosspayments`·`portone`이다. PG가 추가될 수 있어 문자열로 받는다",
+      "결제 서비스 주소. 팝업으로 열려면 쿼리 `mode=popup`을 붙이고, 그대로 이동하면 리다이렉트 결제다",
     ),
-  pgParams: pgParamsSchema,
-  expiresAt: z.string(),
+  expiresAt: z.string().describe("결제 요청 만료 시각"),
   testPayment: z
     .boolean()
     .describe(
@@ -130,27 +191,15 @@ export const paymentParamsSchema = z.object({
     ),
 });
 
-export type PaymentParams = z.infer<typeof paymentParamsSchema>;
-
-export const confirmPaymentRequestSchema = z.object({
-  pgToken: z.string().min(1).describe("PG 승인 키 (토스 `paymentKey`, 포트원 `txId`)"),
-  attemptId: z
-    .string()
-    .min(1)
-    .optional()
-    .describe("승인할 결제 시도 id (결제창이 돌려준 주문번호). 생략하면 현재 시도"),
-});
-
-export type ConfirmPaymentRequest = z.infer<typeof confirmPaymentRequestSchema>;
-
-export const confirmPaymentResultSchema = z.object({
-  orderId: z.string(),
-  status: z.literal("PAID"),
-  totalAmount: z.number().int(),
-  paidAt: z.string(),
-});
+export type PaymentStart = z.infer<typeof paymentStartSchema>;
 
-export type ConfirmPaymentResult = z.infer<typeof confirmPaymentResultSchema>;
+/** 결제창에서 결제하지 못한 이유 */
+export const paymentFailureCategorySchema = z.enum([
+  "PREPARE_FAILURE",
+  "DECLINED",
+  "USER_CANCELED",
+]);
+export type PaymentFailureCategory = z.infer<typeof paymentFailureCategorySchema>;
 
 /**
  * 결제 상태 조회의 현재 상태 값 — 응답 스키마는 서버가 상태를 추가해도 파싱이 깨지지 않게 문자열로 받는다
@@ -165,6 +214,17 @@ export const PAYMENT_STATUS_VALUES = [
 ] as const;
 export type KnownPaymentStatus = (typeof PAYMENT_STATUS_VALUES)[number];
 
+/** 결제 결과 구분 — 결제 서비스가 스토어프론트에 돌려주는 값과 같다 */
+export const PAYMENT_RESULT_VALUES = [
+  "COMPLETED",
+  "PROCESSING",
+  "CANCELED",
+  "FAILED",
+  "EXPIRED",
+  "PENDING",
+] as const;
+export type KnownPaymentResult = (typeof PAYMENT_RESULT_VALUES)[number];
+
 export const paymentStatusSchema = z.object({
   paymentId: z.string(),
   status: z
@@ -173,7 +233,28 @@ export const paymentStatusSchema = z.object({
       "결제 상태. 현재 값은 `pending` 결제 대기 · `processing` 승인 확인 중 · `completed` 결제 완료(주문 생성) · `failed` 실패 · " +
         "`expired` 만료예요. 상태가 추가될 수 있어 문자열로 받아요 — 모르는 값은 `processing`처럼 다루고 계속 조회하세요",
     ),
+  result: z
+    .string()
+    .describe(
+      "화면 분기용 결과. `COMPLETED` 결제 완료 · `PROCESSING` 결과 확인 중 · `CANCELED` 구매자가 결제창을 닫음 · " +
+        "`FAILED` 결제 실패(다른 결제 옵션으로 재시도 가능) · `EXPIRED` 결제 요청 만료 · `PENDING` 결제 전이에요. " +
+        "값이 추가될 수 있어 문자열로 받아요 — 모르는 값은 `PROCESSING`처럼 다루세요",
+    ),
   orderId: z.string().nullable().describe("결제가 완료됐으면 주문 번호, 그 외에는 null"),
+  lastFailure: z
+    .object({
+      attemptId: z.string(),
+      category: z
+        .string()
+        .describe("`PREPARE_FAILURE`·`DECLINED`·`USER_CANCELED`(값이 추가될 수 있다)"),
+      code: z
+        .string()
+        .nullable()
+        .describe("PG가 준 실패 코드. 내부 사유는 null이에요. 화면 분기는 `category`로 하세요"),
+      message: z.string().nullable().describe("구매자에게 보여 줄 안내 문구"),
+    })
+    .nullable()
+    .describe("현재 결제 시도가 실패·취소로 끝났으면 그 내용, 아니면 null"),
   testPayment: z
     .boolean()
     .describe("테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않았어요"),
@@ -181,3 +262,16 @@ export const paymentStatusSchema = z.object({
 });
 
 export type PaymentStatus = z.infer<typeof paymentStatusSchema>;
+
+/**
+ * 결제 서비스가 팝업 opener에 보내는 메시지 — `type`으로 거르고 결과의 원천은 결제 상태 조회다.
+ * 안내 문구는 싣지 않는다. 화면 문구는 상태 조회의 `lastFailure`를 쓴다
+ */
+export const paymentMessageSchema = z.object({
+  type: z.literal("sayren:payment"),
+  paymentId: z.string(),
+  result: z.string(),
+  orderId: z.string().optional(),
+});
+
+export type PaymentMessage = z.infer<typeof paymentMessageSchema>;

package/src/schemas/inquiry.ts

@@ -23,3 +23,11 @@ export const createInquiryRequestSchema = z.object({
 });
 
 export type CreateInquiryRequest = z.infer<typeof createInquiryRequestSchema>;
+
+/** `POST /products/{productId}/inquiries` 응답 */
+export const createInquiryResultSchema = z.object({
+  inquiryId: z.string(),
+  createdAt: z.string(),
+});
+
+export type CreateInquiryResult = z.infer<typeof createInquiryResultSchema>;

package/src/schemas/member.ts

@@ -49,3 +49,11 @@ export const memberAddressRequestSchema = z.object({
 });
 
 export type MemberAddressRequest = z.infer<typeof memberAddressRequestSchema>;
+
+/** `POST /me/wishlist` 응답 — 이미 찜한 상품이어도 같은 응답이다 */
+export const wishlistAddResultSchema = z.object({
+  productId: z.string(),
+  wished: z.literal(true),
+});
+
+export type WishlistAddResult = z.infer<typeof wishlistAddResultSchema>;

package/src/schemas/order.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { paymentMethodSchema } from "./checkout";
+import { easyPayProviderResponseSchema, paymentMethodSchema } from "./checkout";
 import { orderItemStatusSchema } from "./common";
 
 export const myOrderItemSchema = z.object({
@@ -46,6 +46,15 @@ export const myOrderSchema = z.object({
     method: paymentMethodSchema.describe(
       "실제 결제수단(PG가 보고한 수단, 모르면 주문서에서 고른 수단). 결제창에서 바뀔 수 있다(카드 결제창의 간편결제 탭 등)",
     ),
+    easyPayProvider: easyPayProviderResponseSchema
+      .nullable()
+      .optional()
+      .default(null)
+      .describe(
+        "간편결제사. `method`가 `EASY_PAY`일 때만 값이 있고, PG가 알려 주지 않았으면 주문서에서 고른 간편결제사다. " +
+          "그 밖의 결제수단과 간편결제 이전 주문은 null. 서버는 항상 싣는다. " +
+          "현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다",
+      ),
     totalAmount: z.number().int(),
     paidAt: z.string().nullable(),
     receiptUrl: z.url().nullable(),
@@ -74,3 +83,12 @@ export const deliveryTrackingSchema = z.object({
 });
 
 export type DeliveryTracking = z.infer<typeof deliveryTrackingSchema>;
+
+/** `POST /me/order-items/{orderItemId}/purchase-decision` 응답 */
+export const purchaseDecisionResultSchema = z.object({
+  orderItemId: z.string(),
+  status: z.literal("PURCHASE_DECIDED"),
+  decidedAt: z.string(),
+});
+
+export type PurchaseDecisionResult = z.infer<typeof purchaseDecisionResultSchema>;

package/src/schemas/review.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { pageSchema } from "./common";
 
 export const publicReviewSchema = z.object({
   reviewId: z.string(),
@@ -63,3 +64,18 @@ export const updateReviewRequestSchema = z
   });
 
 export type UpdateReviewRequest = z.infer<typeof updateReviewRequestSchema>;
+
+/** `GET /products/{productId}/reviews` 응답 — 리뷰 페이지와 평점 분포 */
+export const reviewPageSchema = pageSchema(publicReviewSchema).extend({
+  summary: reviewSummarySchema.optional(),
+});
+
+export type ReviewPage = z.infer<typeof reviewPageSchema>;
+
+/** `PUT /me/reviews/{reviewId}` 응답 */
+export const updateReviewResultSchema = z.object({
+  reviewId: z.string(),
+  updatedAt: z.string(),
+});
+
+export type UpdateReviewResult = z.infer<typeof updateReviewResultSchema>;

package/src/schemas/store.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 /**
- * 스토어 공개 설정 — `GET /store`. 스토어프런트가 화면을 그릴 때 읽는 값만 담는다.
+ * 스토어 공개 설정 — `GET /store`. 스토어프론트가 화면을 그릴 때 읽는 값만 담는다.
  */
 export const storefrontStoreSchema = z.object({
   storeCode: z.string(),