@sayren/storefront-sdk 0.1.0

package/src/schemas/catalog.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import type { PageParams } from "./common";
+
+export interface CategoryNode {
+  categoryId: string;
+  name: string;
+  depth: number;
+  children: CategoryNode[];
+}
+
+export const categoryNodeSchema: z.ZodType<CategoryNode> = z.lazy(() =>
+  z.object({
+    categoryId: z.string(),
+    name: z.string(),
+    depth: z.number().int().min(1).max(4),
+    children: z.array(categoryNodeSchema),
+  }),
+);
+
+export const productCardSchema = z.object({
+  productId: z.string(),
+  name: z.string(),
+  thumbnailUrl: z.url(),
+  salePrice: z.number().int(),
+  discountedPrice: z.number().int().nullable(),
+  discountRate: z.number().int().nullable(),
+  freeShipping: z.boolean(),
+  averageRating: z.number(),
+  reviewCount: z.number().int(),
+  soldOut: z.boolean(),
+});
+
+export type ProductCard = z.infer<typeof productCardSchema>;
+
+export const productDetailSchema = productCardSchema.extend({
+  description: z.string(),
+  images: z.array(z.url()),
+  /** 옵션 축(그룹). 배열 순서가 곧 표시 순서다 */
+  optionGroups: z.array(
+    z.object({
+      groupId: z.string(),
+      name: z.string(),
+      values: z.array(z.object({ valueId: z.string(), name: z.string() })),
+    }),
+  ),
+  /** 판매 단위(SKU). variantId는 카트·주문의 optionId와 같은 값 공간이다 */
+  variants: z.array(
+    z.object({
+      variantId: z.string(),
+      /** optionGroups 순서와 1:1 대응. 옵션 없는 상품은 [] */
+      valueIds: z.array(z.string()),
+      /** 값 이름을 " / "로 이은 표시명. 옵션 없으면 "" */
+      name: z.string(),
+      additionalPrice: z.number().int(),
+      soldOut: z.boolean(),
+    }),
+  ),
+  delivery: z.object({
+    type: z.enum(["FREE", "PAID", "CONDITIONAL_FREE"]),
+    fee: z.number().int(),
+    conditionalFreeAmount: z.number().int().nullable(),
+    estimatedDays: z.string(),
+  }),
+  returnPolicy: z.object({
+    returnFee: z.number().int(),
+    exchangeFee: z.number().int(),
+    periodDays: z.number().int(),
+  }),
+  categoryPath: z.array(z.object({ categoryId: z.string(), name: z.string() })),
+});
+
+export type ProductDetail = z.infer<typeof productDetailSchema>;
+
+export const productSortSchema = z.enum([
+  "recommend",
+  "latest",
+  "priceAsc",
+  "priceDesc",
+  "reviewCount",
+  "ratingDesc",
+]);
+
+export type ProductSort = z.infer<typeof productSortSchema>;
+
+export interface ProductSearchParams extends PageParams {
+  keyword?: string;
+  categoryId?: string;
+  minPrice?: number;
+  maxPrice?: number;
+  freeShipping?: boolean;
+  sort?: ProductSort;
+}
+
+export const productFacetsSchema = z.object({
+  categories: z
+    .array(z.object({ categoryId: z.string(), name: z.string(), count: z.number().int() }))
+    .optional(),
+  priceRange: z.object({ min: z.number().int(), max: z.number().int() }).optional(),
+});
+
+export type ProductFacets = z.infer<typeof productFacetsSchema>;

package/src/schemas/checkout.ts

@@ -0,0 +1,183 @@
+import { z } from "zod";
+
+export const createCheckoutRequestSchema = z
+  .object({
+    cartItemIds: z.array(z.string()).min(1).optional(),
+    directItem: z
+      .object({
+        productId: z.string(),
+        optionId: z.string().optional(),
+        quantity: z.number().int().min(1),
+      })
+      .optional(),
+  })
+  .refine((value) => (value.cartItemIds ? !value.directItem : !!value.directItem), {
+    message: "cartItemIds와 directItem 중 하나만 전달해야 합니다",
+  });
+
+export type CreateCheckoutRequest = z.infer<typeof createCheckoutRequestSchema>;
+
+export const checkoutSessionSchema = z.object({
+  checkoutId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      productName: z.string(),
+      /** variantId. 옵션 없는 상품은 default variant id */
+      optionId: z.string().nullable(),
+      optionName: z.string().nullable(),
+      quantity: z.number().int(),
+      unitPrice: z.number().int(),
+      totalPrice: z.number().int(),
+    }),
+  ),
+  amounts: z.object({
+    productAmount: z.number().int(),
+    deliveryFee: z.number().int(),
+    totalAmount: z.number().int(),
+  }),
+  expiresAt: z.string(),
+  testPayment: z
+    .boolean()
+    .describe(
+      "지금 결제하면 테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않아요 — 주문서에 테스트 결제 안내를 표시해요. 결제 요청 시점에 스토어 결제 설정으로 다시 정해지니 최종 값은 결제 요청 응답의 `testPayment`예요",
+    ),
+});
+
+export type CheckoutSession = z.infer<typeof checkoutSessionSchema>;
+
+export const paymentMethodSchema = z.enum([
+  "CARD",
+  "BANK_TRANSFER",
+  "VIRTUAL_ACCOUNT",
+  "MOBILE",
+  "EASY_PAY",
+]);
+
+export type PaymentMethod = z.infer<typeof paymentMethodSchema>;
+
+export const shippingAddressInputSchema = z.object({
+  addressId: z.string().optional(),
+  receiverName: z.string().min(1, "수령인명을 입력해주세요").max(50),
+  phone: z.string().regex(/^01[0-9]{8,9}$/, "연락처 형식이 아닙니다 (예: 01012345678)"),
+  zipCode: z.string().regex(/^[0-9]{5}$/, "우편번호는 5자리 숫자입니다"),
+  address1: z.string().min(1, "기본 주소를 입력해주세요"),
+  address2: z.string().optional(),
+  deliveryMemo: z.string().max(100).optional(),
+  entranceCode: z.string().max(20).optional(),
+});
+
+export type ShippingAddressInput = z.infer<typeof shippingAddressInputSchema>;
+
+export const guestInfoSchema = z.object({
+  name: z.string().min(1),
+  phone: z.string().regex(/^01[0-9]{8,9}$/),
+  email: z.email(),
+  orderPassword: z.string().min(6, "주문 조회 비밀번호는 6자 이상이어야 합니다"),
+});
+
+export type GuestInfo = z.infer<typeof guestInfoSchema>;
+
+export const requestPaymentRequestSchema = z.object({
+  shippingAddress: shippingAddressInputSchema,
+  paymentMethod: paymentMethodSchema,
+  guest: guestInfoSchema.optional(),
+});
+
+export type RequestPaymentRequest = z.infer<typeof requestPaymentRequestSchema>;
+
+/**
+ * 결제창 파라미터. 스토어프론트가 쓰는 계약 값은 `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` 실결제). 팝업 내부 값"),
+});
+
+export type PgParams = z.infer<typeof pgParamsSchema>;
+
+export const paymentParamsSchema = z.object({
+  paymentId: z.string(),
+  pgProvider: z
+    .string()
+    .describe(
+      "첫 결제 시도의 PG. 현재 값은 `tosspayments`·`portone`이다. PG가 추가될 수 있어 문자열로 받는다",
+    ),
+  pgParams: pgParamsSchema,
+  expiresAt: z.string(),
+  testPayment: z
+    .boolean()
+    .describe(
+      "테스트 결제(샌드박스) 여부. true면 실제로 돈이 나가지 않는다 — 결제 화면에 테스트 결제 안내를 표시한다",
+    ),
+});
+
+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 ConfirmPaymentResult = z.infer<typeof confirmPaymentResultSchema>;
+
+/**
+ * 결제 상태 조회의 현재 상태 값 — 응답 스키마는 서버가 상태를 추가해도 파싱이 깨지지 않게 문자열로 받는다
+ * (`pgProvider`와 같은 방식). 화면 분기는 이 목록으로 하고 모르는 값은 확인 중으로 다룬다.
+ */
+export const PAYMENT_STATUS_VALUES = [
+  "pending",
+  "processing",
+  "completed",
+  "failed",
+  "expired",
+] as const;
+export type KnownPaymentStatus = (typeof PAYMENT_STATUS_VALUES)[number];
+
+export const paymentStatusSchema = z.object({
+  paymentId: z.string(),
+  status: z
+    .string()
+    .describe(
+      "결제 상태. 현재 값은 `pending` 결제 대기 · `processing` 승인 확인 중 · `completed` 결제 완료(주문 생성) · `failed` 실패 · " +
+        "`expired` 만료예요. 상태가 추가될 수 있어 문자열로 받아요 — 모르는 값은 `processing`처럼 다루고 계속 조회하세요",
+    ),
+  orderId: z.string().nullable().describe("결제가 완료됐으면 주문 번호, 그 외에는 null"),
+  testPayment: z
+    .boolean()
+    .describe("테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않았어요"),
+  expiresAt: z.string().describe("결제 요청 만료 시각"),
+});
+
+export type PaymentStatus = z.infer<typeof paymentStatusSchema>;

package/src/schemas/claim.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { claimStatusSchema } from "./common";
+
+export const claimTypeSchema = z.enum(["CANCEL", "RETURN", "EXCHANGE"]);
+
+export type ClaimType = z.infer<typeof claimTypeSchema>;
+
+export const claimReasonSchema = z.enum([
+  "CHANGE_OF_MIND",
+  "WRONG_ORDER",
+  "DEFECTIVE",
+  "WRONG_DELIVERY",
+  "DIFFERENT_FROM_PAGE",
+  "DELAY",
+]);
+
+export type ClaimReason = z.infer<typeof claimReasonSchema>;
+
+export const createClaimRequestSchema = z.object({
+  type: claimTypeSchema,
+  reason: claimReasonSchema,
+  reasonDetail: z.string().max(1000).optional(),
+  evidenceImages: z.array(z.url()).max(5).optional(),
+  exchangeOptionId: z.string().optional(),
+});
+
+export type CreateClaimRequest = z.infer<typeof createClaimRequestSchema>;
+
+export const createClaimResultSchema = z.object({
+  claimId: z.string(),
+  status: z.literal("REQUESTED"),
+  expectedRefundAmount: z.number().int().nullable(),
+  claimDeliveryFee: z.number().int(),
+});
+
+export type CreateClaimResult = z.infer<typeof createClaimResultSchema>;
+
+export const myClaimSchema = z.object({
+  claimId: z.string(),
+  type: claimTypeSchema,
+  status: claimStatusSchema,
+  orderItemId: z.string(),
+  productName: z.string(),
+  reason: z.string(),
+  expectedRefundAmount: z.number().int().nullable(),
+  rejectReason: z.string().nullable(),
+  requestedAt: z.string(),
+  completedAt: z.string().nullable(),
+});
+
+export type MyClaim = z.infer<typeof myClaimSchema>;

package/src/schemas/common.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+export const pageInfoSchema = z.object({
+  page: z.number().int(),
+  size: z.number().int(),
+  totalElements: z.number().int(),
+  totalPages: z.number().int(),
+});
+
+export type PageInfo = z.infer<typeof pageInfoSchema>;
+
+export function pageSchema<T extends z.ZodType>(item: T) {
+  return pageInfoSchema.extend({ contents: z.array(item) });
+}
+
+export interface PageParams {
+  page?: number;
+  size?: number;
+}
+
+export const orderItemStatusSchema = z.enum([
+  "PAYMENT_WAITING",
+  "PAID",
+  "CONFIRMED",
+  "DISPATCHED",
+  "DELIVERING",
+  "DELIVERED",
+  "PURCHASE_DECIDED",
+  "CANCELED",
+]);
+
+export type OrderItemStatus = z.infer<typeof orderItemStatusSchema>;
+
+export const claimStatusSchema = z.enum([
+  "REQUESTED",
+  "HELD",
+  "COLLECTING",
+  "COLLECTED",
+  "REDELIVERING",
+  "APPROVED",
+  "REJECTED",
+  "COMPLETED",
+  "WITHDRAWN",
+]);
+
+export type ClaimStatus = z.infer<typeof claimStatusSchema>;

package/src/schemas/customer-inquiry.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export const customerInquiryCategorySchema = z.enum([
+  "DELIVERY",
+  "RETURN",
+  "EXCHANGE",
+  "PAYMENT",
+  "ETC",
+]);
+
+export type CustomerInquiryCategory = z.infer<typeof customerInquiryCategorySchema>;
+
+/** 구매자 본인 뷰 — 마스킹 없이 본인 데이터, 셀러 답변(수정횟수 제외) */
+export const customerInquirySchema = z.object({
+  inquiryId: z.string(),
+  category: customerInquiryCategorySchema,
+  title: z.string(),
+  content: z.string(),
+  orderItemId: z.string().nullable(),
+  answered: z.boolean(),
+  answer: z
+    .object({
+      content: z.string(),
+      answeredAt: z.string(),
+    })
+    .nullable(),
+  createdAt: z.string(),
+});
+
+export type CustomerInquiry = z.infer<typeof customerInquirySchema>;
+
+export const createCustomerInquiryRequestSchema = z.object({
+  category: customerInquiryCategorySchema,
+  title: z.string().min(1).max(100),
+  content: z.string().min(1).max(2000),
+  orderItemId: z.string().optional(),
+});
+
+export type CreateCustomerInquiryRequest = z.infer<typeof createCustomerInquiryRequestSchema>;

package/src/schemas/inquiry.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+export const publicInquirySchema = z.object({
+  inquiryId: z.string(),
+  content: z.string().nullable(),
+  secret: z.boolean(),
+  mine: z.boolean(),
+  writerMaskedName: z.string(),
+  answer: z
+    .object({
+      content: z.string().nullable(),
+      answeredAt: z.string(),
+    })
+    .nullable(),
+  createdAt: z.string(),
+});
+
+export type PublicInquiry = z.infer<typeof publicInquirySchema>;
+
+export const createInquiryRequestSchema = z.object({
+  content: z.string().min(1).max(1000),
+  secret: z.boolean().default(false),
+});
+
+export type CreateInquiryRequest = z.infer<typeof createInquiryRequestSchema>;

package/src/schemas/member.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+export const memberSchema = z.object({
+  memberId: z.string(),
+  email: z.email(),
+  name: z.string(),
+  phone: z.string().nullable(),
+  point: z.number().int(),
+  marketingAgreed: z.boolean(),
+  joinedAt: z.string(),
+});
+
+export type Member = z.infer<typeof memberSchema>;
+
+export const updateProfileRequestSchema = z
+  .object({
+    name: z.string().max(50).optional(),
+    phone: z.string().optional(),
+    marketingAgreed: z.boolean().optional(),
+  })
+  .refine((value) => Object.values(value).some((v) => v !== undefined), {
+    message: "최소 1개 필드가 필요합니다",
+  });
+
+export type UpdateProfileRequest = z.infer<typeof updateProfileRequestSchema>;
+
+export const memberAddressSchema = z.object({
+  addressId: z.string(),
+  alias: z.string(),
+  isDefault: z.boolean(),
+  receiverName: z.string(),
+  phone: z.string(),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullable(),
+});
+
+export type MemberAddress = z.infer<typeof memberAddressSchema>;
+
+export const memberAddressRequestSchema = z.object({
+  alias: z.string().min(1).max(20),
+  receiverName: z.string().min(1).max(50),
+  phone: z.string().regex(/^01[0-9]{8,9}$/),
+  zipCode: z.string().regex(/^[0-9]{5}$/),
+  address1: z.string().min(1),
+  address2: z.string().optional(),
+  isDefault: z.boolean().default(false),
+});
+
+export type MemberAddressRequest = z.infer<typeof memberAddressRequestSchema>;

package/src/schemas/order.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { paymentMethodSchema } from "./checkout";
+import { orderItemStatusSchema } from "./common";
+
+export const myOrderItemSchema = z.object({
+  orderItemId: z.string(),
+  productId: z.string(),
+  productName: z.string(),
+  thumbnailUrl: z.url(),
+  optionName: z.string().nullable(),
+  quantity: z.number().int(),
+  totalPrice: z.number().int(),
+  status: orderItemStatusSchema,
+  claimStatus: z.string().nullable(),
+  reviewWritten: z.boolean(),
+  autoDecisionDate: z.string().nullable(),
+});
+
+export type MyOrderItem = z.infer<typeof myOrderItemSchema>;
+
+/**
+ * 주문 응답의 배송지 — 결제 요청 시 저장된 스냅샷. 요청 스키마(`shippingAddressInputSchema`)와 분리한 응답 스키마라
+ * 형식 검증(regex·길이)을 하지 않는다. 입력하지 않은 선택 필드는 null로 오거나 빠질 수 있다.
+ */
+export const orderShippingAddressSchema = z.object({
+  receiverName: z.string(),
+  phone: z.string(),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullish().describe("상세 주소. 입력하지 않았으면 null이거나 없다"),
+  deliveryMemo: z.string().nullish().describe("배송 메모. 입력하지 않았으면 null이거나 없다"),
+  entranceCode: z
+    .string()
+    .nullish()
+    .describe("공동현관 출입번호. 입력하지 않았으면 null이거나 없다"),
+});
+
+export type OrderShippingAddress = z.infer<typeof orderShippingAddressSchema>;
+
+export const myOrderSchema = z.object({
+  orderId: z.string(),
+  orderedAt: z.string(),
+  items: z.array(myOrderItemSchema),
+  shippingAddress: orderShippingAddressSchema,
+  payment: z.object({
+    method: paymentMethodSchema.describe(
+      "실제 결제수단(PG가 보고한 수단, 모르면 주문서에서 고른 수단). 결제창에서 바뀔 수 있다(카드 결제창의 간편결제 탭 등)",
+    ),
+    totalAmount: z.number().int(),
+    paidAt: z.string().nullable(),
+    receiptUrl: z.url().nullable(),
+  }),
+  testPayment: z
+    .boolean()
+    .describe(
+      "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 나가지 않았어요 — 주문 화면에 테스트 결제 배지를 표시해요",
+    ),
+});
+
+export type MyOrder = z.infer<typeof myOrderSchema>;
+
+export const deliveryTrackingSchema = z.object({
+  carrierName: z.string(),
+  trackingNumber: z.string(),
+  trackingUrl: z.url(),
+  status: z.enum(["DISPATCHED", "DELIVERING", "DELIVERED"]),
+  trackingEvents: z.array(
+    z.object({
+      status: z.string(),
+      location: z.string(),
+      occurredAt: z.string(),
+    }),
+  ),
+});
+
+export type DeliveryTracking = z.infer<typeof deliveryTrackingSchema>;

package/src/schemas/review.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+export const publicReviewSchema = z.object({
+  reviewId: z.string(),
+  rating: z.number().int().min(1).max(5),
+  content: z.string(),
+  images: z.array(z.url()),
+  optionName: z.string().nullable(),
+  writerMaskedName: z.string(),
+  sellerReply: z
+    .object({
+      content: z.string(),
+      repliedAt: z.string(),
+    })
+    .nullable(),
+  createdAt: z.string(),
+});
+
+export type PublicReview = z.infer<typeof publicReviewSchema>;
+
+export const reviewSummarySchema = z.object({
+  averageRating: z.number(),
+  totalCount: z.number().int(),
+  distribution: z.record(z.string(), z.number().int()),
+});
+
+export type ReviewSummary = z.infer<typeof reviewSummarySchema>;
+
+export const writableReviewSchema = z.object({
+  orderItemId: z.string(),
+  productId: z.string(),
+  productName: z.string(),
+  optionName: z.string().nullable(),
+  thumbnailUrl: z.url(),
+  writableUntil: z.string(),
+});
+
+export type WritableReview = z.infer<typeof writableReviewSchema>;
+
+export const createReviewRequestSchema = z.object({
+  rating: z.number().int().min(1).max(5),
+  content: z.string().min(10, "리뷰는 10자 이상 작성해주세요").max(2000),
+  images: z.array(z.url()).max(5).optional(),
+});
+
+export type CreateReviewRequest = z.infer<typeof createReviewRequestSchema>;
+
+export const createReviewResultSchema = z.object({
+  reviewId: z.string(),
+  rewardPoint: z.number().int(),
+});
+
+export type CreateReviewResult = z.infer<typeof createReviewResultSchema>;
+
+export const updateReviewRequestSchema = z
+  .object({
+    rating: z.number().int().min(1).max(5).optional(),
+    content: z.string().min(10).max(2000).optional(),
+    images: z.array(z.url()).max(5).optional(),
+  })
+  .refine((value) => Object.values(value).some((v) => v !== undefined), {
+    message: "최소 1개 필드가 필요합니다",
+  });
+
+export type UpdateReviewRequest = z.infer<typeof updateReviewRequestSchema>;