@sayren/store-sdk 0.1.0

package/src/schemas/product.ts

@@ -0,0 +1,272 @@
+import { z } from "zod";
+import type { PageParams } from "./common";
+
+export const productStatusSchema = z.enum(["SALE", "SUSPENDED", "OUT_OF_STOCK", "CLOSED"]);
+
+export type ProductStatus = z.infer<typeof productStatusSchema>;
+
+export const deliveryTypeSchema = z.enum(["FREE", "PAID", "CONDITIONAL_FREE"]);
+
+export type DeliveryType = z.infer<typeof deliveryTypeSchema>;
+
+export const productSummarySchema = z.object({
+  productId: z.string(),
+  name: z.string(),
+  status: productStatusSchema,
+  salePrice: z.number().int(),
+  discountedPrice: z.number().int().nullable(),
+  /** usable variant 재고 합계 (서버 계산) */
+  stockQuantity: z.number().int(),
+  categoryId: z.string().nullable(),
+  thumbnailUrl: z.url().optional(),
+  /** optionGroups.length > 0 */
+  hasOptions: z.boolean(),
+  updatedAt: z.string(),
+});
+
+export type ProductSummary = z.infer<typeof productSummarySchema>;
+
+/** 옵션 축(그룹)이 가지는 값 하나 — 예: 축 "색상"의 값 "블랙" */
+export const optionValueSchema = z.object({
+  valueId: z.string(),
+  name: z.string(),
+  sortOrder: z.number().int(),
+});
+
+export type OptionValue = z.infer<typeof optionValueSchema>;
+
+/** 옵션 축(그룹) — 예: "색상", "사이즈" */
+export const optionGroupSchema = z.object({
+  groupId: z.string(),
+  name: z.string(),
+  sortOrder: z.number().int(),
+  values: z.array(optionValueSchema),
+});
+
+export type OptionGroup = z.infer<typeof optionGroupSchema>;
+
+/**
+ * 판매 단위(SKU). variantId는 기존 optionId 값 공간을 승계하므로
+ * 카트·주문·리뷰·클레임의 optionId가 곧 variantId다.
+ */
+export const productVariantSchema = z.object({
+  variantId: z.string(),
+  /** 축 sortOrder 순서와 1:1 대응. 옵션 없는 상품은 [] */
+  valueIds: z.array(z.string()),
+  /** 값 이름을 " / "로 이은 파생 표시명. 옵션 없으면 "" */
+  name: z.string(),
+  additionalPrice: z.number().int(),
+  stockQuantity: z.number().int(),
+  sku: z.string().nullable(),
+  barcode: z.string().nullable(),
+  costPrice: z.number().int().nullable(),
+  weightGram: z.number().int().nullable(),
+  sellerCode: z.string().nullable(),
+  usable: z.boolean(),
+});
+
+export type ProductVariant = z.infer<typeof productVariantSchema>;
+
+export const productSchema = productSummarySchema.extend({
+  description: z.string().optional(),
+  /**
+   * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
+   * 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
+   */
+  descriptionJson: z.string().nullable().optional(),
+  originalPrice: z.number().int().nullable().optional(),
+  images: z.array(z.url()).optional(),
+  attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
+  optionGroups: z.array(optionGroupSchema),
+  /** 모든 상품이 최소 1개 variant를 갖는다 (옵션 없으면 default variant 1개) */
+  variants: z.array(productVariantSchema),
+  deliveryType: deliveryTypeSchema.optional(),
+  deliveryFee: z.number().int().optional(),
+  conditionalFreeAmount: z.number().int().nullable().optional(),
+  returnFee: z.number().int().optional(),
+  exchangeFee: z.number().int().optional(),
+  shippingAddressId: z.string().nullable().optional(),
+  returnAddressId: z.string().nullable().optional(),
+  createdAt: z.string().optional(),
+});
+
+export type Product = z.infer<typeof productSchema>;
+
+/** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
+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
+ * (`WHERE ... is not null`)의 판정이 갈려 409 대신 500이 나간다.
+ */
+const codeSchema = z.string().trim().min(1).max(64);
+
+export const optionValueRequestSchema = z.object({
+  /** 전달 시 기존 값 행을 유지(UPDATE). 생략하면 신규 발급 */
+  valueId: z.string().optional(),
+  name: z.string().min(1).max(50),
+});
+
+export type OptionValueRequest = z.infer<typeof optionValueRequestSchema>;
+
+export const optionGroupRequestSchema = z.object({
+  /** 전달 시 기존 축 행을 유지(UPDATE). 생략하면 신규 발급 */
+  groupId: z.string().optional(),
+  name: z.string().min(1).max(50),
+  values: z.array(optionValueRequestSchema).min(1).max(MAX_VALUES_PER_GROUP),
+});
+
+export type OptionGroupRequest = z.infer<typeof optionGroupRequestSchema>;
+
+export const productVariantRequestSchema = z.object({
+  /** 기존 variant 유지 시 전달. 생략하면 신규 생성 */
+  variantId: z.string().optional(),
+  /** optionGroups 순서대로 각 축에서 고른 값 이름. 서버가 이름 → valueId를 해석한다 */
+  valueNames: z.array(z.string()).default([]),
+  additionalPrice: z.number().int().default(0),
+  /**
+   * 생략 = 기존 재고 유지 (신규 variant는 0).
+   * 구조 교체(PUT)가 폼 로드 시점의 재고를 되쓰지 않게 하는 옵트인 필드다 —
+   * 재고만 바꿀 때는 PATCH /products/{id}/variants/{variantId}/stock을 쓴다.
+   */
+  stockQuantity: z.number().int().min(0).optional(),
+  sku: codeSchema.optional(),
+  barcode: codeSchema.optional(),
+  costPrice: z.number().int().min(0).optional(),
+  weightGram: z.number().int().min(0).optional(),
+  sellerCode: codeSchema.optional(),
+  usable: z.boolean().default(true),
+});
+
+export type ProductVariantRequest = z.infer<typeof productVariantRequestSchema>;
+
+/** 축 × 값 → variant 전체 교체 요청 (PUT /products/{productId}/options) */
+export const optionModelRequestSchema = z.object({
+  optionGroups: z.array(optionGroupRequestSchema).max(MAX_OPTION_GROUPS).default([]),
+  variants: z.array(productVariantRequestSchema).min(1).max(MAX_VARIANTS),
+});
+
+export type OptionModelRequest = z.infer<typeof optionModelRequestSchema>;
+
+/** GET /products/{productId}/options 응답 */
+export const optionModelSchema = z.object({
+  optionGroups: z.array(optionGroupSchema),
+  variants: z.array(productVariantSchema),
+});
+
+export type OptionModel = z.infer<typeof optionModelSchema>;
+
+/**
+ * 재고 변경 택일 위반 문구 — SDK `.refine`과 서버 DomainException이 공유하는 단일 원천.
+ * 경로에 따라 셀러가 다른 문구를 받지 않게 한다.
+ */
+export const VARIANT_STOCK_EXCLUSIVE_MESSAGE =
+  "stockQuantity 또는 adjustment 중 하나만 전달해야 합니다";
+
+/**
+ * variant 재고 변경 요청 — 절대값(`stockQuantity`) 또는 증감(`adjustment`) 택일.
+ * 서버도 같은 규칙을 400 VALIDATION_FAILED로 검증한다(이중 방어).
+ */
+export const variantStockRequestSchema = z
+  .object({
+    stockQuantity: z.number().int().min(0).optional(),
+    adjustment: z.number().int().optional(),
+  })
+  .refine((v) => (v.stockQuantity !== undefined) !== (v.adjustment !== undefined), {
+    message: VARIANT_STOCK_EXCLUSIVE_MESSAGE,
+  });
+
+export type VariantStockRequest = z.infer<typeof variantStockRequestSchema>;
+
+/** PATCH /products/{productId}/variants/{variantId}/stock 응답 */
+export const variantStockSchema = z.object({
+  variantId: z.string(),
+  stockQuantity: z.number().int(),
+});
+
+export type VariantStock = z.infer<typeof variantStockSchema>;
+
+export const productCreateRequestSchema = z
+  .object({
+    name: z.string().min(1).max(100),
+    categoryId: z.string().min(1, "카테고리를 선택해주세요"),
+    salePrice: z
+      .number()
+      .int()
+      .min(10)
+      .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)"),
+    originalPrice: z.number().int().optional(),
+    description: z.string().optional(),
+    /**
+     * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
+     * 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
+     */
+    descriptionJson: z.string().nullable().optional(),
+    images: z.array(z.url()).min(1).max(10).optional(),
+    attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
+    deliveryType: deliveryTypeSchema.default("PAID"),
+    deliveryFee: z.number().int().default(0),
+    conditionalFreeAmount: z.number().int().optional(),
+    returnFee: z.number().int().default(0),
+    exchangeFee: z.number().int().default(0),
+    shippingAddressId: z.string().optional(),
+    returnAddressId: z.string().optional(),
+  })
+  .extend(optionModelRequestSchema.shape);
+
+export type ProductCreateRequest = z.infer<typeof productCreateRequestSchema>;
+
+export const productPatchRequestSchema = z
+  .object({
+    name: z.string().max(100).optional(),
+    salePrice: z.number().int().multipleOf(10).optional(),
+    status: productStatusSchema.optional(),
+    deliveryFee: z.number().int().optional(),
+  })
+  .refine((value) => Object.values(value).some((v) => v !== undefined), {
+    message: "최소 1개 필드가 필요합니다",
+  });
+
+export type ProductPatchRequest = z.infer<typeof productPatchRequestSchema>;
+
+export type ProductSort =
+  | "createdAt.desc"
+  | "createdAt.asc"
+  | "salePrice.asc"
+  | "salePrice.desc"
+  | "updatedAt.desc";
+
+export interface ProductListParams extends PageParams {
+  status?: ProductStatus;
+  categoryId?: string;
+  keyword?: string;
+  sellerCode?: string;
+  sort?: ProductSort;
+}
+
+export const discountSchema = z.object({
+  productId: z.string(),
+  discountType: z.enum(["RATE", "AMOUNT"]),
+  discountValue: z.number().int(),
+  discountedPrice: z.number().int(),
+  startAt: z.string().nullable(),
+  endAt: z.string().nullable(),
+});
+
+export type Discount = z.infer<typeof discountSchema>;
+
+export const discountRequestSchema = z.object({
+  discountType: z.enum(["RATE", "AMOUNT"]),
+  discountValue: z.number().int().min(1),
+  startAt: z.string().optional(),
+  endAt: z.string().optional(),
+});
+
+export type DiscountRequest = z.infer<typeof discountRequestSchema>;
+
+// 카테고리 스키마는 ./category 로 이관됨 (배럴에서 노출).

package/src/schemas/scope.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import type { StoreRole } from "./auth";
+
+/**
+ * 스토어 스코프 카탈로그 (auth-spec §7) — 형식 `{리소스}:{r|rw}`, rw는 r을 함의한다.
+ *
+ * 관리 API가 요구하는 스코프와 역할별 자동 부여 스코프의 **단일 원천**이다.
+ * 서버(apps/api)가 이 상수를 그대로 가져다 역할→스코프를 산출하므로, 콘솔 권한 매트릭스와
+ * 서버 인가가 갈라지지 않는다.
+ */
+
+export const scopeAccessSchema = z
+  .enum(["r", "rw"])
+  .describe("접근 수준. `r`=읽기, `rw`=읽기+쓰기(r을 함의)");
+export type ScopeAccess = z.infer<typeof scopeAccessSchema>;
+
+/** 리소스별로 부여 가능한 접근 수준. settlement는 쓰기 API가 없어 `r`만 존재한다 */
+export const STORE_SCOPE_RESOURCES = {
+  product: ["r", "rw"],
+  category: ["r", "rw"],
+  order: ["r", "rw"],
+  claim: ["r", "rw"],
+  inquiry: ["r", "rw"],
+  review: ["r", "rw"],
+  settlement: ["r"],
+  webhook: ["r", "rw"],
+  store: ["r", "rw"],
+  member: ["r", "rw"],
+} as const satisfies Record<string, readonly ScopeAccess[]>;
+
+export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
+
+export const storeScopeResourceSchema = z
+  .enum(Object.keys(STORE_SCOPE_RESOURCES) as [StoreScopeResource, ...StoreScopeResource[]])
+  .describe("스코프 리소스");
+
+/** 카탈로그상 존재하는 스코프 문자열인가 (예: `settlement:rw`는 false) */
+export function isStoreScope(scope: string): boolean {
+  const [resource, access, ...rest] = scope.split(":");
+  if (rest.length > 0 || !resource || !access) return false;
+  const allowed = (STORE_SCOPE_RESOURCES as Record<string, readonly string[]>)[resource];
+  return allowed?.includes(access) ?? false;
+}
+
+/**
+ * 역할별 자동 부여 스코프 (auth-spec §7).
+ * storeToken(사람)의 스코프는 이 표로 결정된다. PAT·M2M 클라이언트에는 역할이 없고
+ * 발급 시 지정한 스코프만 갖는다(발급자 보유 스코프 이내).
+ */
+export const STORE_ROLE_SCOPES = {
+  OWNER: [
+    "product:rw",
+    "category:rw",
+    "order:rw",
+    "claim:rw",
+    "inquiry:rw",
+    "review:rw",
+    "settlement:r",
+    "webhook:rw",
+    "store:rw",
+    "member:rw",
+  ],
+  ADMIN: [
+    "product:rw",
+    "category:rw",
+    "order:rw",
+    "claim:rw",
+    "inquiry:rw",
+    "review:rw",
+    "webhook:rw",
+    "store:rw",
+    "member:rw",
+  ],
+  STAFF: ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw"],
+} as const satisfies Record<StoreRole, readonly string[]>;

package/src/schemas/store.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { storeRoleSchema } from "./auth";
+
+/**
+ * 스토어 코드 규칙 — 스토어프론트 API가 테넌트를 가르는 값이다(`X-Store-Code` 헤더).
+ * **개설할 때 서버가 랜덤으로 발급하고** 이후 바꿀 수 없다. 이미 나간 링크와 승인된 결제가
+ * 이 값에 묶여 있어서 바꾸면 함께 깨진다.
+ *
+ * 호스트 라벨로도 쓸 수 있게 DNS 라벨 규칙까지 좁힌다. 하이픈으로 시작하거나 끝나는 라벨은 호스트가 될 수 없다.
+ */
+export const STORE_CODE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
+
+/** 플랫폼이 쓰거나 쓸 호스트 이름 — 스토어 코드로 내주지 않는다 */
+export const RESERVED_STORE_CODES: readonly string[] = [
+  "www",
+  "api",
+  "store",
+  "stores",
+  "checkout",
+  "docs",
+  "admin",
+  "app",
+  "console",
+  "dashboard",
+  "platform",
+  "internal",
+  "auth",
+  "login",
+  "oauth",
+  "account",
+  "accounts",
+  "pay",
+  "payment",
+  "payments",
+  "webhook",
+  "webhooks",
+  "status",
+  "support",
+  "help",
+  "blog",
+  "cdn",
+  "static",
+  "assets",
+  "img",
+  "images",
+  "media",
+  "mail",
+  "smtp",
+  "ftp",
+  "ns",
+  "ns1",
+  "ns2",
+  "mx",
+  "dev",
+  "test",
+  "staging",
+  "stage",
+  "sandbox",
+];
+
+export function isReservedStoreCode(code: string): boolean {
+  return RESERVED_STORE_CODES.includes(code.toLowerCase());
+}
+
+export const storeCodeSchema = z
+  .string()
+  .regex(
+    STORE_CODE_PATTERN,
+    "소문자·숫자·하이픈 3~30자여야 하고 하이픈으로 시작하거나 끝날 수 없어요",
+  )
+  .refine(
+    (code) => !isReservedStoreCode(code),
+    "플랫폼이 쓰는 이름이라 스토어 코드로 쓸 수 없어요",
+  );
+
+export const storeSchema = z.object({
+  storeId: z.string(),
+  name: z.string(),
+  storeCode: z.string(),
+  storefrontUrl: z.url(),
+  status: z.enum(["ACTIVE", "SUSPENDED", "CLOSED"]),
+  logoUrl: z.url().nullable(),
+  businessNumber: z.string().nullable(),
+  customerCenterPhone: z.string().nullable(),
+  memberCount: z.number().int(),
+  createdAt: z.string(),
+});
+
+export type Store = z.infer<typeof storeSchema>;
+
+export const storeMemberSchema = z.object({
+  userId: z.string(),
+  name: z.string(),
+  email: z.email(),
+  role: storeRoleSchema,
+  joinedAt: z.string(),
+  lastActiveAt: z.string().nullable(),
+});
+
+export type StoreMember = z.infer<typeof storeMemberSchema>;
+
+export const invitationSchema = z.object({
+  invitationId: z.string(),
+  email: z.email(),
+  role: z.enum(["ADMIN", "STAFF"]),
+  status: z.enum(["PENDING", "ACCEPTED", "EXPIRED", "CANCELED"]),
+  invitedBy: z.string(),
+  expiresAt: z.string(),
+  createdAt: z.string(),
+});
+
+export type Invitation = z.infer<typeof invitationSchema>;
+
+export const addressTypeSchema = z.enum(["SHIPPING", "RETURN"]);
+
+export type AddressType = z.infer<typeof addressTypeSchema>;
+
+export const sellerAddressSchema = z.object({
+  addressId: z.string(),
+  type: addressTypeSchema,
+  name: z.string(),
+  isDefault: z.boolean(),
+  contactName: z.string(),
+  phone: z.string(),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().optional(),
+  createdAt: z.string(),
+});
+
+export type SellerAddress = z.infer<typeof sellerAddressSchema>;
+
+export const sellerAddressRequestSchema = z.object({
+  type: addressTypeSchema,
+  name: z.string().min(1).max(50),
+  contactName: z.string().min(1),
+  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(),
+});
+
+export type SellerAddressRequest = z.infer<typeof sellerAddressRequestSchema>;

package/src/schemas/upload.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+/**
+ * 미디어 업로드 자리 발급 — `POST /v1/uploads`.
+ *
+ * 파일 바이트는 api를 거치지 않는다. 응답의 `uploadUrl`로 클라이언트가 직접 PUT하고,
+ * 끝나면 `url`이 공개 주소가 된다. 서버가 객체 키를 정하므로 요청은 파일명만 보낸다
+ * (확장자만 쓰이고 이름 자체는 저장되지 않는다).
+ */
+export const uploadRequestSchema = z.object({
+  filename: z.string().min(1).max(255),
+});
+
+export type UploadRequest = z.infer<typeof uploadRequestSchema>;
+
+export const uploadTicketSchema = z.object({
+  /** 업로드 완료 후 공개될 주소 */
+  url: z.url(),
+  /** 파일 바이트를 PUT할 presigned URL. 1시간 유효 */
+  uploadUrl: z.url(),
+});
+
+export type UploadTicket = z.infer<typeof uploadTicketSchema>;

package/src/schemas/webhook-event.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { claimStatusSchema, claimTypeSchema } from "./claim";
+import { orderItemStatusSchema } from "./common";
+
+/**
+ * 웹훅 발송 형식 (공개 계약). 본문은 얇은 이벤트다. 개인정보를 싣지 않으며
+ * 수신자는 `data`의 id로 관리 API를 조회해 최신 상태를 얻는다.
+ *
+ * 서명 생성·검증은 시크릿을 다루므로 서버 엔트리포인트(`@sayren/store-sdk/server`)에 있다.
+ */
+
+export {
+  WEBHOOK_DEFAULT_TOLERANCE_SEC,
+  WEBHOOK_DELIVERY_ID_HEADER,
+  WEBHOOK_EVENT_ID_HEADER,
+  WEBHOOK_EVENT_TYPE_HEADER,
+  WEBHOOK_HEADERS,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_USER_AGENT,
+} from "../webhook-headers";
+
+const envelopeFields = {
+  id: z.string().describe("이벤트 ID (`evt_…`, 테스트 전송은 `evt_test_…`). 중복 제거 키"),
+  createdAt: z.string().describe("이벤트 발생 일시 (ISO 8601)"),
+  storeId: z.string().describe("이벤트가 발생한 스토어 ID"),
+};
+
+export const orderWebhookEventDataSchema = z.object({
+  orderId: z.string().describe("주문 ID"),
+  status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
+  testPayment: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다. 이 필드가 없는 이전 이벤트는 false로 읽는다",
+    ),
+});
+export type OrderWebhookEventData = z.infer<typeof orderWebhookEventDataSchema>;
+
+export const claimWebhookEventDataSchema = z.object({
+  claimId: z.string().describe("클레임 ID"),
+  orderId: z.string().describe("주문 ID"),
+  orderItemId: z.string().describe("클레임 대상 주문 상품 ID"),
+  claimType: claimTypeSchema.describe("클레임 유형"),
+  status: claimStatusSchema.describe("이벤트 발생 시점의 클레임 상태"),
+  testPayment: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "테스트 결제(샌드박스 결제) 주문의 클레임인가. 이 필드가 없는 이전 이벤트는 false로 읽는다",
+    ),
+});
+export type ClaimWebhookEventData = z.infer<typeof claimWebhookEventDataSchema>;
+
+export const inquiryWebhookEventDataSchema = z.object({
+  inquiryId: z.string().describe("상품 문의 ID"),
+  productId: z.string().describe("상품 ID"),
+});
+export type InquiryWebhookEventData = z.infer<typeof inquiryWebhookEventDataSchema>;
+
+export const reviewWebhookEventDataSchema = z.object({
+  reviewId: z.string().describe("리뷰 ID"),
+  productId: z.string().describe("상품 ID"),
+  rating: z.number().int().min(1).max(5).describe("별점 (1~5)"),
+});
+export type ReviewWebhookEventData = z.infer<typeof reviewWebhookEventDataSchema>;
+
+export const productOutOfStockWebhookEventDataSchema = z.object({
+  productId: z.string().describe("상품 ID"),
+  variantId: z
+    .string()
+    .describe("재고가 0이 된 판매 단위(variant) ID. 주문 상품의 `optionId`와 같은 값 공간이다"),
+});
+export type ProductOutOfStockWebhookEventData = z.infer<
+  typeof productOutOfStockWebhookEventDataSchema
+>;
+
+export const orderWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.enum([
+    "ORDER.PAID",
+    "ORDER.CONFIRMED",
+    "ORDER.DISPATCHED",
+    "ORDER.DELIVERED",
+    "ORDER.PURCHASE_DECIDED",
+    "ORDER.ADDRESS_CHANGE_REQUESTED",
+  ]),
+  data: orderWebhookEventDataSchema,
+});
+
+export const claimWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.enum([
+    "CLAIM.CANCEL_REQUESTED",
+    "CLAIM.RETURN_REQUESTED",
+    "CLAIM.EXCHANGE_REQUESTED",
+    "CLAIM.COMPLETED",
+  ]),
+  data: claimWebhookEventDataSchema,
+});
+
+export const inquiryWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("INQUIRY.CREATED"),
+  data: inquiryWebhookEventDataSchema,
+});
+
+export const reviewWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("REVIEW.CREATED"),
+  data: reviewWebhookEventDataSchema,
+});
+
+export const productOutOfStockWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("PRODUCT.OUT_OF_STOCK"),
+  data: productOutOfStockWebhookEventDataSchema,
+});
+
+/** 웹훅 요청 본문. `type`으로 판별하며 `data` 형태가 타입별로 다르다 */
+export const webhookEventSchema = z
+  .discriminatedUnion("type", [
+    orderWebhookEventSchema,
+    claimWebhookEventSchema,
+    inquiryWebhookEventSchema,
+    reviewWebhookEventSchema,
+    productOutOfStockWebhookEventSchema,
+  ])
+  .describe(
+    "웹훅 요청 본문 (얇은 이벤트). 개인정보를 싣지 않으며 `data`의 id로 관리 API를 조회한다",
+  );
+export type WebhookEvent = z.infer<typeof webhookEventSchema>;
+
+export type WebhookEventType = WebhookEvent["type"];
+
+/** 이벤트 타입 하나로 좁힌 이벤트 (예: `WebhookEventOf<"ORDER.PAID">["data"]`) */
+export type WebhookEventOf<T extends WebhookEventType> = WebhookEvent extends infer E
+  ? E extends { type: infer U }
+    ? T extends U
+      ? Omit<E, "type"> & { type: T }
+      : never
+    : never
+  : never;

package/src/server.ts

@@ -0,0 +1,24 @@
+/**
+ * 서버 엔트리포인트 (`@sayren/store-sdk/server`) — 시크릿을 다루는 헬퍼만 둔다.
+ * 브라우저 번들에서 import하지 않는다.
+ */
+
+export {
+  WEBHOOK_DEFAULT_TOLERANCE_SEC,
+  WEBHOOK_DELIVERY_ID_HEADER,
+  WEBHOOK_EVENT_ID_HEADER,
+  WEBHOOK_EVENT_TYPE_HEADER,
+  WEBHOOK_HEADERS,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_USER_AGENT,
+} from "./webhook-headers";
+export {
+  type ParsedWebhookSignature,
+  parseWebhookSignatureHeader,
+  type SignWebhookPayloadOptions,
+  signWebhookPayload,
+  type VerifyWebhookSignatureOptions,
+  verifyWebhookSignature,
+  type WebhookSignatureFailureReason,
+  type WebhookSignatureVerification,
+} from "./webhook-signature";