@sayren/store-sdk 0.1.0

package/src/schemas/category.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+
+export const categoryProductSortSchema = z.enum([
+  "RECENT",
+  "POPULAR",
+  "PRICE_LOW",
+  "PRICE_HIGH",
+  "NAME",
+]);
+
+export type CategoryProductSort = z.infer<typeof categoryProductSortSchema>;
+
+export const categorySchema = z.object({
+  categoryId: z.string(),
+  storeId: z.string(),
+  name: z.string(),
+  parentId: z.string().nullable(),
+  path: z.string(),
+  depth: z.number().int().min(1).max(4),
+  leaf: z.boolean(),
+  sortOrder: z.number().int(),
+  visible: z.boolean(),
+  showPc: z.boolean(),
+  showMobile: z.boolean(),
+  productSort: categoryProductSortSchema,
+  metaTitle: z.string().nullable(),
+  metaDescription: z.string().nullable(),
+  metaKeywords: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export type Category = z.infer<typeof categorySchema>;
+
+export type CategoryTreeNode = Category & { children: CategoryTreeNode[] };
+export const categoryTreeNodeSchema: z.ZodType<CategoryTreeNode> = categorySchema.extend({
+  children: z.lazy(() => z.array(categoryTreeNodeSchema)),
+});
+
+export const categoryWithPathSchema = categorySchema.extend({
+  fullPath: z.string(),
+  ancestors: z.array(categorySchema),
+  childCount: z.number().int(),
+});
+
+export type CategoryWithPath = z.infer<typeof categoryWithPathSchema>;
+
+export const categorySearchResultSchema = categorySchema.extend({
+  fullPath: z.string(),
+  ancestors: z.array(categorySchema),
+});
+
+export type CategorySearchResult = z.infer<typeof categorySearchResultSchema>;
+
+export const categoryAttributeSchema = z.object({
+  attributeId: z.string(),
+  name: z.string(),
+  required: z.boolean(),
+  inputType: z.enum(["SELECT", "MULTI_SELECT", "TEXT", "NUMBER"]),
+  unit: z.string().nullable(),
+  allowedValues: z.array(z.string()).optional(),
+});
+
+export type CategoryAttribute = z.infer<typeof categoryAttributeSchema>;
+
+export const categoryCreateRequestSchema = z.object({
+  name: z.string().min(1).max(100),
+  parentId: z.string().nullable().optional(),
+  sortOrder: z.number().int().optional(),
+  visible: z.boolean().optional(),
+  showPc: z.boolean().optional(),
+  showMobile: z.boolean().optional(),
+  productSort: categoryProductSortSchema.optional(),
+  metaTitle: z.string().max(100).nullable().optional(),
+  metaDescription: z.string().max(300).nullable().optional(),
+  metaKeywords: z.string().max(200).nullable().optional(),
+});
+
+export type CategoryCreateRequest = z.infer<typeof categoryCreateRequestSchema>;
+
+export const categoryPatchRequestSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  parentId: z.string().nullable().optional(),
+  sortOrder: z.number().int().optional(),
+  visible: z.boolean().optional(),
+  showPc: z.boolean().optional(),
+  showMobile: z.boolean().optional(),
+  productSort: categoryProductSortSchema.optional(),
+  metaTitle: z.string().max(100).nullable().optional(),
+  metaDescription: z.string().max(300).nullable().optional(),
+  metaKeywords: z.string().max(200).nullable().optional(),
+});
+
+export type CategoryPatchRequest = z.infer<typeof categoryPatchRequestSchema>;
+
+export const categoryDeleteStrategySchema = z.enum(["reparent", "cascade"]);
+
+export type CategoryDeleteStrategy = z.infer<typeof categoryDeleteStrategySchema>;

package/src/schemas/claim.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import type { PageParams } from "./common";
+
+export const claimTypeSchema = z.enum(["CANCEL", "RETURN", "EXCHANGE"]);
+
+export type ClaimType = z.infer<typeof claimTypeSchema>;
+
+export const claimStatusSchema = z.enum([
+  "REQUESTED",
+  "HELD",
+  "COLLECTING",
+  "COLLECTED",
+  "REDELIVERING",
+  "APPROVED",
+  "REJECTED",
+  "COMPLETED",
+  "WITHDRAWN",
+]);
+
+export type ClaimStatus = z.infer<typeof claimStatusSchema>;
+
+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 claimSchema = z.object({
+  claimId: z.string(),
+  type: claimTypeSchema,
+  status: claimStatusSchema,
+  orderId: z.string(),
+  orderItemId: z.string(),
+  productName: z.string(),
+  quantity: z.number().int(),
+  reason: claimReasonSchema,
+  reasonDetail: z.string().nullable(),
+  responsibility: z.enum(["BUYER", "SELLER"]),
+  claimDeliveryFee: z.number().int(),
+  expectedRefundAmount: z.number().int().nullable(),
+  exchangeOption: z.object({ optionId: z.string(), optionName: z.string() }).nullable(),
+  collect: z
+    .object({
+      method: z.enum(["SELLER_PICKUP", "BUYER_SEND"]),
+      carrierCode: z.string().nullable(),
+      trackingNumber: z.string().nullable(),
+    })
+    .nullable(),
+  requestedAt: z.string(),
+  completedAt: z.string().nullable(),
+});
+
+export type Claim = z.infer<typeof claimSchema>;
+
+export interface ClaimListParams extends PageParams {
+  type?: ClaimType;
+  status?: ClaimStatus;
+  orderItemId?: string;
+  requestedFrom?: string;
+  requestedTo?: string;
+}
+
+export const rejectClaimRequestSchema = z.object({
+  reason: z.enum([
+    "USED_PRODUCT",
+    "MISSING_COMPONENT",
+    "PERIOD_EXPIRED",
+    "BUYER_FAULT_DAMAGE",
+    "ETC",
+  ]),
+  detail: z.string().min(10).max(1000),
+  evidenceImages: z.array(z.url()).max(5).optional(),
+});
+
+export type RejectClaimRequest = z.infer<typeof rejectClaimRequestSchema>;
+
+export const approveClaimResultSchema = z.object({
+  claimId: z.string(),
+  refundAmount: z.number().int(),
+  deductAmount: z.number().int(),
+  refundedAt: z.string(),
+});
+
+export type ApproveClaimResult = z.infer<typeof approveClaimResultSchema>;

package/src/schemas/common.ts

@@ -0,0 +1,61 @@
+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 bulkResultSchema = z.object({
+  succeeded: z.array(z.string()),
+  failed: z.array(
+    z.object({
+      id: z.string().optional(),
+      productId: z.string().optional(),
+      orderItemId: z.string().optional(),
+      code: z.string(),
+      message: z.string(),
+    }),
+  ),
+});
+
+export type BulkResult = z.infer<typeof bulkResultSchema>;
+
+export const orderItemStatusSchema = z.enum([
+  "PAYMENT_WAITING",
+  "PAID",
+  "CONFIRMED",
+  "DISPATCHED",
+  "DELIVERING",
+  "DELIVERED",
+  "PURCHASE_DECIDED",
+  "CANCELED",
+]);
+
+export type OrderItemStatus = z.infer<typeof orderItemStatusSchema>;
+
+export const changeTypeSchema = z.enum([
+  "ORDER.PAID",
+  "ORDER.CONFIRMED",
+  "ORDER.DISPATCHED",
+  "ORDER.DELIVERED",
+  "ORDER.PURCHASE_DECIDED",
+  "CLAIM.CANCEL_REQUESTED",
+  "CLAIM.RETURN_REQUESTED",
+  "CLAIM.EXCHANGE_REQUESTED",
+  "ORDER.ADDRESS_CHANGE_REQUESTED",
+]);
+
+export type ChangeType = z.infer<typeof changeTypeSchema>;

package/src/schemas/misc.ts

@@ -0,0 +1,298 @@
+import { z } from "zod";
+import type { PageParams } from "./common";
+
+export const inquirySchema = z.object({
+  inquiryId: z.string(),
+  productId: z.string(),
+  productName: z.string(),
+  orderItemId: z.string().nullable(),
+  category: z.enum(["PRODUCT", "DELIVERY", "RETURN", "EXCHANGE", "ETC"]),
+  content: z.string(),
+  secret: z.boolean(),
+  writerMaskedName: z.string(),
+  answered: z.boolean(),
+  answer: z
+    .object({
+      content: z.string(),
+      answeredAt: z.string(),
+      modifiedCount: z.number().int().max(1),
+    })
+    .nullable(),
+  createdAt: z.string(),
+});
+
+export type Inquiry = z.infer<typeof inquirySchema>;
+
+export const customerInquiryCategorySchema = z.enum([
+  "DELIVERY",
+  "RETURN",
+  "EXCHANGE",
+  "PAYMENT",
+  "ETC",
+]);
+
+export type CustomerInquiryCategory = z.infer<typeof customerInquiryCategorySchema>;
+
+/** 셀러 뷰 1:1 문의 — 작성자 마스킹명 + 답변 수정횟수 포함 */
+export const sellerCustomerInquirySchema = z.object({
+  inquiryId: z.string(),
+  memberMaskedName: 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(),
+      modifiedCount: z.number().int().max(1),
+    })
+    .nullable(),
+  createdAt: z.string(),
+});
+
+export type SellerCustomerInquiry = z.infer<typeof sellerCustomerInquirySchema>;
+
+export const settlementStatusSchema = z.enum(["SCHEDULED", "PAID", "HELD"]);
+
+export type SettlementStatus = z.infer<typeof settlementStatusSchema>;
+
+export const settlementSummarySchema = z.object({
+  settlementId: z.string(),
+  settlementDate: z.string(),
+  payoutDate: z.string().nullable(),
+  status: settlementStatusSchema,
+  totalPaymentAmount: z.number().int(),
+  totalCommission: z.number().int(),
+  totalDeliveryFee: z.number().int(),
+  adjustmentAmount: z.number().int(),
+  settlementAmount: z.number().int(),
+  itemCount: z.number().int(),
+});
+
+export type SettlementSummary = z.infer<typeof settlementSummarySchema>;
+
+export const settlementDetailSchema = z.object({
+  orderItemId: z.string(),
+  productName: z.string(),
+  settlementType: z.enum(["SALE", "REFUND_DEDUCTION", "ADJUSTMENT"]),
+  paymentAmount: z.number().int(),
+  salesCommission: z.number().int(),
+  paymentCommission: z.number().int(),
+  commissionRate: z.number(),
+  deliveryFee: z.number().int(),
+  settlementAmount: z.number().int(),
+  purchaseDecidedAt: z.string().nullable(),
+});
+
+export type SettlementDetail = z.infer<typeof settlementDetailSchema>;
+
+export interface SettlementListParams extends PageParams {
+  from: string;
+  to?: string;
+  status?: SettlementStatus;
+}
+
+export const eventTypeSchema = z.enum([
+  "ORDER.PAID",
+  "ORDER.CONFIRMED",
+  "ORDER.DISPATCHED",
+  "ORDER.DELIVERED",
+  "ORDER.PURCHASE_DECIDED",
+  "ORDER.ADDRESS_CHANGE_REQUESTED",
+  "CLAIM.CANCEL_REQUESTED",
+  "CLAIM.RETURN_REQUESTED",
+  "CLAIM.EXCHANGE_REQUESTED",
+  "CLAIM.COMPLETED",
+  "INQUIRY.CREATED",
+  "REVIEW.CREATED",
+  "PRODUCT.OUT_OF_STOCK",
+]);
+
+export type EventType = z.infer<typeof eventTypeSchema>;
+
+export const webhookStatusSchema = z
+  .enum(["ACTIVE", "SUSPENDED"])
+  .describe(
+    "구독 상태. `ACTIVE`=발송 대상, `SUSPENDED`=24시간 이상 연속 전송 실패로 발송이 정지된 상태. 정지 중 발생한 이벤트는 적재하지 않는다. 재개(`POST /webhooks/{id}/resume`)하거나 구독을 수정하면 ACTIVE로 돌아간다",
+  );
+export type WebhookStatus = z.infer<typeof webhookStatusSchema>;
+
+export const webhookSchema = z.object({
+  webhookId: z.string(),
+  url: z.url(),
+  eventTypes: z.array(eventTypeSchema),
+  status: webhookStatusSchema,
+  secretPrefix: z
+    .string()
+    .describe("서명 시크릿 앞부분(식별용, 서명 검증에 사용할 수 없음). 예: `whsec_1a2b`"),
+  suspendedAt: z.string().nullable().describe("발송이 정지된 일시 (ISO 8601). `ACTIVE`면 null"),
+  createdAt: z.string(),
+});
+
+export type Webhook = z.infer<typeof webhookSchema>;
+
+/** 등록 응답 — 서명 시크릿 평문은 이 응답에서만 노출된다 */
+export const webhookCreatedSchema = webhookSchema.extend({
+  secret: z.string().describe("서명 시크릿 평문. 등록 응답에서만 노출되며 다시 조회할 수 없다"),
+});
+export type WebhookCreated = z.infer<typeof webhookCreatedSchema>;
+
+/** 시크릿 교체 응답 */
+export const webhookSecretRotatedSchema = z.object({
+  secret: z.string().describe("새 서명 시크릿 평문. 이 응답에서만 노출된다"),
+  oldSecretExpiresAt: z
+    .string()
+    .describe(
+      "기존 시크릿의 병행 유효 종료 일시 (ISO 8601). 이때까지는 기존 시크릿 서명도 함께 붙는다",
+    ),
+});
+export type WebhookSecretRotated = z.infer<typeof webhookSecretRotatedSchema>;
+
+export const webhookDeliveryStatusSchema = z
+  .enum(["PENDING", "PENDING_RETRY", "SUCCESS", "FAILED"])
+  .describe(
+    "전송 상태. `PENDING`=첫 시도 전, `PENDING_RETRY`=실패 후 재시도 대기, `SUCCESS`=2xx 응답 수신, `FAILED`=재시도를 모두 소진했거나 구독 정지로 종료",
+  );
+export type WebhookDeliveryStatus = z.infer<typeof webhookDeliveryStatusSchema>;
+
+export const webhookDeliveryErrorCodeSchema = z
+  .enum(["TIMEOUT", "CONNECTION_FAILED", "BLOCKED_ADDRESS", "NON_2XX", "WEBHOOK_SUSPENDED"])
+  .describe(
+    "전송 실패 사유. `TIMEOUT`=10초 안에 응답 없음, `CONNECTION_FAILED`=연결 실패(DNS·TLS 포함), `BLOCKED_ADDRESS`=사설·루프백 등 전송이 허용되지 않는 주소, `NON_2XX`=2xx가 아닌 응답(리다이렉트 포함), `WEBHOOK_SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨",
+  );
+export type WebhookDeliveryErrorCode = z.infer<typeof webhookDeliveryErrorCodeSchema>;
+
+/** 웹훅 전송 기록 한 건 (전송 기록 조회 항목) */
+export const webhookDeliverySchema = z.object({
+  deliveryId: z.string().describe("전송 기록 ID. 수신 요청의 `Sayren-Delivery-Id` 헤더 값"),
+  eventId: z
+    .string()
+    .describe(
+      "이벤트 ID. 재시도·재전송해도 같은 이벤트면 같은 값이다. 수신 측 중복 제거 키로 쓴다",
+    ),
+  eventType: eventTypeSchema,
+  url: z.string().describe("전송 시점의 대상 URL"),
+  status: webhookDeliveryStatusSchema,
+  responseStatusCode: z
+    .number()
+    .int()
+    .nullable()
+    .describe("마지막 시도의 HTTP 응답 코드. 미시도·연결 실패·타임아웃·차단이면 null"),
+  responseTimeMs: z
+    .number()
+    .int()
+    .nullable()
+    .describe("마지막 시도의 응답 시간(ms). 미시도·연결 실패면 null"),
+  responseBodyExcerpt: z
+    .string()
+    .nullable()
+    .describe("마지막 시도의 응답 본문 앞부분(최대 1,024자). 응답이 없으면 null"),
+  errorCode: webhookDeliveryErrorCodeSchema
+    .nullable()
+    .describe("마지막 시도의 실패 사유. 성공했거나 미시도면 null"),
+  attemptCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe("지금까지의 시도 횟수. 최초 시도 1회 + 재시도 최대 4회"),
+  createdAt: z.string().describe("전송 기록이 적재된 일시 (ISO 8601)"),
+  attemptedAt: z.string().nullable().describe("마지막 시도 일시 (ISO 8601). 미시도면 null"),
+  nextAttemptAt: z
+    .string()
+    .nullable()
+    .describe("다음 시도 예정 일시 (ISO 8601). `PENDING`·`PENDING_RETRY`일 때만 값이 있다"),
+  redeliveryOf: z
+    .string()
+    .nullable()
+    .describe("수동 재전송으로 생긴 기록이면 원본 전송 기록 ID. 아니면 null"),
+  redeliveredAs: z
+    .string()
+    .nullable()
+    .describe(
+      "이 기록을 원본으로 수동 재전송해 생긴 기록의 전송 기록 ID. 아직 재전송하지 않았으면 null. 재전송은 원본당 1회다",
+    ),
+});
+export type WebhookDelivery = z.infer<typeof webhookDeliverySchema>;
+
+/** 전송 기록 조회 쿼리 — `GET /webhooks/{id}/deliveries` */
+export const webhookDeliveryListQuerySchema = z.object({
+  status: webhookDeliveryStatusSchema.optional().describe("전송 상태 필터. 생략하면 전체"),
+  limit: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("최대 건수 (1~100, 기본 50). 최신 적재순으로 반환하며 보관 기간은 30일이다"),
+});
+export type WebhookDeliveryListParams = z.infer<typeof webhookDeliveryListQuerySchema>;
+
+/** 실패 건 일괄 재전송 응답 — `POST /webhooks/{id}/deliveries/redeliver-failed` */
+export const webhookRedeliverFailedResultSchema = z.object({
+  queued: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "재전송 대기열에 올린 건수. 최근 72시간의 `FAILED` 중 아직 재전송되지 않은 건이 대상이며 최대 500건이다",
+    ),
+});
+export type WebhookRedeliverFailedResult = z.infer<typeof webhookRedeliverFailedResultSchema>;
+
+export const webhookTestRequestSchema = z.object({
+  eventType: eventTypeSchema.describe("샘플 페이로드로 보낼 이벤트 타입"),
+});
+export type WebhookTestRequest = z.infer<typeof webhookTestRequestSchema>;
+
+/** 테스트 이벤트 발송 결과 (동기 반환). 재시도·정지 판정·전송 기록이 없다 */
+export const webhookTestResultSchema = z.object({
+  responseStatusCode: z
+    .number()
+    .int()
+    .nullable()
+    .describe("수신 서버의 HTTP 응답 코드. 연결 실패·타임아웃·차단이면 null"),
+  responseTimeMs: z.number().int().nullable().describe("응답 시간(ms). 연결 실패면 null"),
+  errorCode: webhookDeliveryErrorCodeSchema.nullable().describe("실패 사유. 2xx 응답이면 null"),
+});
+export type WebhookTestResult = z.infer<typeof webhookTestResultSchema>;
+
+export const webhookRequestSchema = z.object({
+  url: z.url().startsWith("https://", "웹훅 URL은 HTTPS만 허용됩니다"),
+  eventTypes: z.array(eventTypeSchema).min(1),
+});
+
+export type WebhookRequest = z.infer<typeof webhookRequestSchema>;
+
+export const reviewSchema = z.object({
+  reviewId: z.string(),
+  productId: z.string(),
+  productName: z.string(),
+  orderItemId: z.string(),
+  optionName: z.string().nullable(),
+  rating: z.number().int().min(1).max(5),
+  content: z.string(),
+  images: z.array(z.url()),
+  writerMaskedName: z.string(),
+  blinded: z.boolean(),
+  reply: z
+    .object({
+      content: z.string(),
+      repliedAt: z.string(),
+      updatedAt: z.string().nullable(),
+    })
+    .nullable(),
+  createdAt: z.string(),
+});
+
+export type Review = z.infer<typeof reviewSchema>;
+
+export interface ReviewListParams extends PageParams {
+  productId?: string;
+  rating?: number;
+  replied?: boolean;
+  hasImage?: boolean;
+  from?: string;
+  sort?: "createdAt.desc" | "createdAt.asc" | "rating.asc" | "rating.desc";
+}