@sayren/store-sdk 0.29.2 → 0.29.3

package/src/schemas/points.ts

@@ -44,6 +44,40 @@ export const purchaseEarnPolicySchema = z.object({
 });
 export type PurchaseEarnPolicy = z.infer<typeof purchaseEarnPolicySchema>;
 
+/** 사용 단위 — 1·10·100원 */
+export const POINT_USE_UNITS = [1, 10, 100] as const;
+
+/**
+ * 적립금 사용 규칙(P3) — 주문서에서 결제 금액을 줄인다. 적용 순서는 즉시할인 → 쿠폰 → 적립금이고, 상품 금액(쿠폰 뒤)에 먼저 쓰고
+ * 남으면 배송비에 쓴다(`includeDeliveryFee`). 결제 금액이 100원 아래로 내려가지 않게 적립금을 줄인다.
+ */
+export const pointUsePolicySchema = z.object({
+  enabled: z.boolean().describe("적립금 사용 여부. 꺼도 잔액은 남는다"),
+  minBalance: z
+    .number()
+    .int()
+    .min(0)
+    .max(10_000_000)
+    .describe("이 잔액 이상이어야 쓸 수 있다(원). 0이면 제한 없음"),
+  minAmount: z
+    .number()
+    .int()
+    .min(0)
+    .max(10_000_000)
+    .describe("한 번에 쓰는 최소 금액(원). 0이면 제한 없음"),
+  unit: z
+    .union([z.literal(1), z.literal(10), z.literal(100)])
+    .describe("사용 단위(원). 요청 금액을 이 단위로 내린다"),
+  maxRatioBp: z
+    .number()
+    .int()
+    .min(1)
+    .max(10_000)
+    .describe("결제 기준 금액(쿠폰 뒤) 대비 최대 사용 비율(만분율, 10000 = 100%)"),
+  includeDeliveryFee: z.boolean().describe("배송비에도 쓰는가. 끄면 상품 금액(쿠폰 뒤)에만 쓴다"),
+});
+export type PointUsePolicy = z.infer<typeof pointUsePolicySchema>;
+
 const expiryDays = z
   .number()
   .int()
@@ -58,6 +92,7 @@ const expiryDays = z
 export const pointPolicySchema = z.object({
   reviewReward: reviewRewardPolicySchema,
   purchaseEarn: purchaseEarnPolicySchema,
+  use: pointUsePolicySchema,
   expiryDays: expiryDays.nullable().describe("적립금 유효 기간(일). 정하지 않았으면 null"),
 });
 export type PointPolicy = z.infer<typeof pointPolicySchema>;
@@ -66,6 +101,14 @@ export type PointPolicy = z.infer<typeof pointPolicySchema>;
 export const POINT_POLICY_DEFAULTS: PointPolicy = {
   reviewReward: { enabled: false, textPoint: 0, photoPoint: 0 },
   purchaseEarn: { enabled: false, rateBp: 0 },
+  use: {
+    enabled: false,
+    minBalance: 0,
+    minAmount: 0,
+    unit: 10,
+    maxRatioBp: 10_000,
+    includeDeliveryFee: true,
+  },
   expiryDays: null,
 };
 
@@ -78,10 +121,12 @@ export function resolvePointPolicy(stored: unknown): PointPolicy {
   const raw = stored as Record<string, unknown>;
   const review = reviewRewardPolicySchema.safeParse(raw.reviewReward);
   const purchase = purchaseEarnPolicySchema.safeParse(raw.purchaseEarn);
+  const use = pointUsePolicySchema.safeParse(raw.use);
   const expiry = expiryDays.nullable().safeParse(raw.expiryDays ?? null);
   return {
     reviewReward: review.success ? review.data : POINT_POLICY_DEFAULTS.reviewReward,
     purchaseEarn: purchase.success ? purchase.data : POINT_POLICY_DEFAULTS.purchaseEarn,
+    use: use.success ? use.data : POINT_POLICY_DEFAULTS.use,
     expiryDays: expiry.success ? expiry.data : null,
   };
 }
@@ -137,7 +182,7 @@ export const POINT_LOT_SOURCES = [
 ] as const;
 export type PointLotSource = (typeof POINT_LOT_SOURCES)[number];
 
-/** 원장 항목 유형. 지금 쓰는 것은 리뷰 적립·회수이고 나머지는 다음 단계 자리다 */
+/** 원장 항목 유형 */
 export const POINT_ENTRY_TYPES = [
   "EARN_REVIEW",
   "REVOKE_REVIEW",
@@ -173,6 +218,20 @@ export const storePointPolicySchema = z.object({
   purchaseEarn: purchaseEarnPolicySchema.describe(
     "구매 적립. 구매확정 때 주문상품 실결제 금액(배송비 제외) × 적립률을 준다. 정하지 않았으면 끔·0",
   ),
+  useAvailable: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "적립금 사용(결제에 쓰기)을 켤 수 있는가 (#93). false면 준비 중이라 `use.enabled`를 켜는 저장이 409 `POINTS_UNAVAILABLE`이다. " +
+        "필드가 없는 이전 응답은 false로 읽는다",
+    ),
+  use: pointUsePolicySchema
+    .optional()
+    .default(POINT_POLICY_DEFAULTS.use)
+    .describe(
+      "적립금 사용 규칙. 적용 순서는 즉시할인 → 쿠폰 → 적립금이다. 정하지 않았으면 끔. 필드가 없는 이전 응답은 끔으로 읽는다",
+    ),
   expiryDays: pointPolicySchema.shape.expiryDays,
   notice: pointPolicyNoticeSchema,
 });
@@ -185,6 +244,7 @@ export type StorePointPolicy = z.infer<typeof storePointPolicySchema>;
 export const updatePointPolicyRequestSchema = z.object({
   reviewReward: reviewRewardPolicySchema.optional(),
   purchaseEarn: purchaseEarnPolicySchema.optional(),
+  use: pointUsePolicySchema.optional(),
   expiryDays: expiryDays.optional(),
 });
 export type UpdatePointPolicyRequest = z.infer<typeof updatePointPolicyRequestSchema>;
@@ -196,7 +256,8 @@ export const responsePointEntryTypeSchema = z
   .union([z.enum(POINT_ENTRY_TYPES), z.string()])
   .describe(
     "유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · " +
-      "`OPENING` 기존 잔액 이전. 값이 추가될 수 있어 문자열로 받는다",
+      "`OPENING` 기존 잔액 이전 · `USE_RESERVE` 결제 사용(결제 시작 때 빠짐) · `USE_RELEASE` 결제가 실패·만료되어 되돌림 · " +
+      "`REFUND_RESTORE` 취소·반품 환불로 반환. 값이 추가될 수 있어 문자열로 받는다",
   );
 
 /** 원장 항목 — 셀러 조회용(사유·행위자 포함) */
@@ -222,7 +283,7 @@ export const pointLotSchema = z.object({
   lotId: z.string(),
   source: z
     .union([z.enum(POINT_LOT_SOURCES), z.string()])
-    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`OPENING` 등"),
+    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`REFUND_RESTORE`·`OPENING` 등"),
   amount: z.number().int().describe("적립한 금액"),
   remaining: z.number().int().describe("남은 금액"),
   expiresAt: z.string().nullable().describe("소멸 시각. null이면 소멸 없음"),
@@ -283,3 +344,50 @@ export const pointAdjustmentResultSchema = z.object({
   balance: z.number().int().describe("조정 뒤 잔액"),
 });
 export type PointAdjustmentResult = z.infer<typeof pointAdjustmentResultSchema>;
+
+// ── 사용·환불 (P3) ─────────────────────────────────────
+
+/** 결제 시작에 쓴 적립 묶음 — 해제·환불 반환이 이 값으로 되돌리고 반환 적립금의 만료를 정한다 */
+export interface PointLotUsage {
+  lotId: string;
+  amount: number;
+  expiresAt: string | null;
+}
+
+const RESTORE_GRACE_MS = 30 * DAY_MS;
+
+/**
+ * 환불로 돌려주는 적립금의 만료 — 결제에 쓴 묶음 중 가장 늦은 만료이고, 그 시각이 이미 지났으면 지금 + 30일(KST 날짜 끝)이다.
+ * 쓴 묶음 중 만료 없는 묶음(기존 잔액 등)이 있으면 만료 없음(null)이다. 쓴 기록이 없으면 지금 + 30일이다(사용자 결정 2026-10-02).
+ */
+export function pointRestoreExpiresAtOf(usages: readonly PointLotUsage[], now: Date): Date | null {
+  if (usages.some((usage) => usage.expiresAt === null)) return null;
+  const latest = usages.reduce<number | null>((max, usage) => {
+    const at = Date.parse(usage.expiresAt as string);
+    return Number.isFinite(at) && (max === null || at > max) ? at : max;
+  }, null);
+  if (latest !== null && latest > now.getTime()) return new Date(latest);
+  return pointExpiresAtOf(new Date(now.getTime() + RESTORE_GRACE_MS), 0);
+}
+
+/**
+ * 환불 금액 나누기 — 현금 몫·적립금 몫에서 차감(반품 배송비·쿠폰 조건 미달·추가 차감)을 **현금에서 먼저** 빼고 모자란 몫만 적립금에서 뺀다.
+ * 둘 다 모자라면 0에서 멈추고 못 받은 차감액(`uncollected`)을 돌려준다(호출부가 감사 로그에 남긴다).
+ */
+export function splitRefund(input: { cash: number; points: number; charges: number }): {
+  cashRefund: number;
+  pointRefund: number;
+  uncollected: number;
+} {
+  const cash = Math.max(0, input.cash);
+  const points = Math.max(0, input.points);
+  const charges = Math.max(0, input.charges);
+  const fromCash = Math.min(cash, charges);
+  const rest = charges - fromCash;
+  const fromPoints = Math.min(points, rest);
+  return {
+    cashRefund: cash - fromCash,
+    pointRefund: points - fromPoints,
+    uncollected: rest - fromPoints,
+  };
+}

package/src/schemas/promotion.ts

@@ -219,8 +219,31 @@ export interface PricingDelivery {
   bundles: ReadonlyArray<{ bundleKey: string; fee: number; remoteSurcharge: number }>;
 }
 
+/**
+ * 적립금 사용 입력(#93 P3) — 쿠폰 뒤 금액에 쓴다. 규칙은 상점 정책 `use`(`PointUsePolicy`)의 값이다.
+ * 금액은 요청·잔액·최대 비율 중 작은 값을 `unit`으로 내리고, 남는 결제 금액이 100원 아래로 내려가지 않게 줄인다(적립금 전액 결제는 아직 받지 않는다).
+ */
+export interface PricingPoints {
+  /** 구매자가 쓰겠다는 금액 */
+  requested: number;
+  /** 지금 잔액 */
+  balance: number;
+  rules: {
+    minBalance: number;
+    minAmount: number;
+    unit: number;
+    maxRatioBp: number;
+    includeDeliveryFee: boolean;
+  };
+}
+
+/** 적립금을 쓰지 못한 이유 */
+export type PointRejectReason = "MIN_BALANCE" | "MIN_AMOUNT" | "NOT_PAYABLE";
+
 export interface PricingInput {
   lines: readonly PricingLine[];
+  /** 적립금 사용(#93 P3). 없으면 쓰지 않는다 — 결과는 적립금 이전과 같다 */
+  points?: PricingPoints | null;
   coupons: readonly PricingCoupon[];
   /** 배송비 견적. 없으면 배송비 0으로 계산하고 배송비 쿠폰은 할인할 금액이 없다 */
   delivery?: PricingDelivery | null;
@@ -251,6 +274,8 @@ export interface PricingLineResult {
   /** 이 줄에 들어간 쿠폰 할인 합계 — 상품 쿠폰 + 주문 쿠폰 배분 */
   couponDiscount: number;
   allocations: CouponAllocation[];
+  /** 이 줄에 배분한 사용 적립금(#93 P3). 적립금을 쓰지 않으면 0 */
+  pointAllocation: number;
 }
 
 export interface PricingCouponResult {
@@ -270,6 +295,8 @@ export interface PricingCouponResult {
 export interface PricingBundleResult {
   bundleKey: string;
   couponDiscount: number;
+  /** 이 배송 묶음에 배분한 사용 적립금(#93 P3) */
+  pointAllocation: number;
 }
 
 export interface PricingResult {
@@ -285,7 +312,15 @@ export interface PricingResult {
   deliveryFee: number;
   /** 배송비 쿠폰 할인 */
   deliveryDiscountAmount: number;
-  /** 결제 금액 = productAmount − couponDiscountAmount + deliveryFee − deliveryDiscountAmount */
+  /** 사용 적립금(#93 P3). 쓰지 않으면 0 */
+  pointAmount: number;
+  /** 지금 쓸 수 있는 최대 적립금 — 주문서 안내값(잔액을 모두 요청했을 때의 금액). 적립금 입력이 없으면 0 */
+  pointMaxUsable: number;
+  /** 요청보다 적게 썼다면 그 이유 — `MIN_PAYMENT`: 결제 금액 100원을 남기려고 줄였다 */
+  pointAdjustReason: "MIN_PAYMENT" | null;
+  /** 요청했지만 쓰지 못했다면 그 이유 */
+  pointRejectReason: PointRejectReason | null;
+  /** 결제 금액 = productAmount − couponDiscountAmount + deliveryFee − deliveryDiscountAmount − pointAmount */
   totalAmount: number;
 }
 
@@ -541,6 +576,7 @@ export function quotePricing(input: PricingInput): PricingResult {
   const bundles: PricingBundleResult[] = deliveryBundles.map((bundle) => ({
     bundleKey: bundle.bundleKey,
     couponDiscount: 0,
+    pointAllocation: 0,
   }));
   let deliverySlot = false;
   let deliveryDiscountAmount = 0;
@@ -574,6 +610,7 @@ export function quotePricing(input: PricingInput): PricingResult {
     amount: entry.line.amount,
     couponDiscount: entry.allocations.reduce((sum, a) => sum + a.amount, 0),
     allocations: entry.allocations,
+    pointAllocation: 0,
   }));
   const productAmount = lines.reduce((sum, entry) => sum + entry.line.amount, 0);
   const couponDiscountAmount = lineResults.reduce((sum, line) => sum + line.couponDiscount, 0);
@@ -581,6 +618,33 @@ export function quotePricing(input: PricingInput): PricingResult {
     (sum, bundle) => sum + bundle.fee + bundle.remoteSurcharge,
     0,
   );
+  const beforePoints = productAmount - couponDiscountAmount + deliveryFee - deliveryDiscountAmount;
+
+  // 5) 적립금(#93 P3) — 쿠폰 뒤 금액에 쓴다. 상품 줄에 먼저(줄 실결제 비율), 남으면 배송 묶음에(묶음 실배송비 비율) 배분한다
+  const productWeights = lineResults.map((line) => Math.max(0, line.amount - line.couponDiscount));
+  const bundleWeights = deliveryBundles.map((bundle, index) =>
+    Math.max(0, bundle.fee + bundle.remoteSurcharge - (bundles[index]?.couponDiscount ?? 0)),
+  );
+  const points = pointUseOf(input.points ?? null, {
+    productPaid: productWeights.reduce((sum, w) => sum + w, 0),
+    deliveryPaid: bundleWeights.reduce((sum, w) => sum + w, 0),
+    total: beforePoints,
+  });
+  if (points.amount > 0) {
+    const productPaid = productWeights.reduce((sum, w) => sum + w, 0);
+    const toLines = Math.min(points.amount, productPaid);
+    allocateByWeight(toLines, productWeights).forEach((share, i) => {
+      const line = lineResults[i];
+      if (line) line.pointAllocation = share;
+    });
+    const toBundles = points.amount - toLines;
+    if (toBundles > 0) {
+      allocateByWeight(toBundles, bundleWeights).forEach((share, i) => {
+        const bundle = bundles[i];
+        if (bundle) bundle.pointAllocation = share;
+      });
+    }
+  }
   return {
     lines: lineResults,
     coupons: results,
@@ -589,10 +653,56 @@ export function quotePricing(input: PricingInput): PricingResult {
     couponDiscountAmount,
     deliveryFee,
     deliveryDiscountAmount,
-    totalAmount: productAmount - couponDiscountAmount + deliveryFee - deliveryDiscountAmount,
+    pointAmount: points.amount,
+    pointMaxUsable: points.maxUsable,
+    pointAdjustReason: points.adjustReason,
+    pointRejectReason: points.rejectReason,
+    totalAmount: beforePoints - points.amount,
   };
 }
 
+/**
+ * 사용 적립금 금액(순수) — 요청·잔액·최대 비율·「결제 금액 100원 남기기」 중 작은 값을 단위로 내린다.
+ * 최소 보유액·최소 사용액에 못 미치면 0이다. 결제 금액이 0원이 되는 사용(적립금 전액 결제)은 아직 받지 않는다(P4).
+ */
+export function pointUseOf(
+  points: PricingPoints | null,
+  amounts: { productPaid: number; deliveryPaid: number; total: number },
+): {
+  amount: number;
+  maxUsable: number;
+  adjustReason: "MIN_PAYMENT" | null;
+  rejectReason: PointRejectReason | null;
+} {
+  const none = { amount: 0, maxUsable: 0, adjustReason: null, rejectReason: null };
+  if (!points) return none;
+  const { rules } = points;
+  const unit = Math.max(1, Math.floor(rules.unit));
+  const base = amounts.productPaid + (rules.includeDeliveryFee ? amounts.deliveryPaid : 0);
+  const byRatio = Math.floor((base * rules.maxRatioBp) / 10_000);
+  // 결제 금액은 0원 또는 100원 이상이어야 하고, 지금은 0원 결제를 받지 않으므로 100원을 남긴다
+  const byPayment = Math.max(0, amounts.total - MIN_PAYMENT_AMOUNT);
+  const balance = Math.max(0, points.balance);
+  const floorUnit = (value: number) => Math.floor(Math.max(0, value) / unit) * unit;
+  const eligible = balance >= rules.minBalance;
+  const ceiling = Math.min(balance, byRatio, byPayment);
+  const maxUsable = eligible && floorUnit(ceiling) >= rules.minAmount ? floorUnit(ceiling) : 0;
+  const requested = Math.max(0, Math.floor(points.requested));
+  if (requested === 0) return { ...none, maxUsable };
+  if (!eligible) return { amount: 0, maxUsable, adjustReason: null, rejectReason: "MIN_BALANCE" };
+  const amount = floorUnit(Math.min(requested, balance, byRatio, byPayment));
+  if (amount <= 0) {
+    return { amount: 0, maxUsable, adjustReason: null, rejectReason: "NOT_PAYABLE" };
+  }
+  if (amount < rules.minAmount) {
+    return { amount: 0, maxUsable, adjustReason: null, rejectReason: "MIN_AMOUNT" };
+  }
+  // 요청이 결제 금액 100원 남기기에 걸려 줄었다
+  const adjustReason =
+    floorUnit(Math.min(requested, balance, byRatio)) > amount ? "MIN_PAYMENT" : null;
+  return { amount, maxUsable, adjustReason, rejectReason: null };
+}
+
 // ─── 환불 정산: 조건 미달 차감 ─────────────────────────────
 
 /**
@@ -799,10 +909,36 @@ export function settleCouponShortfall(input: CouponSettlementInput): CouponSettl
  * 바로 나누면 몫이 항상 0 이상이고 전량 취소의 합이 실결제 금액과 정확히 같다.
  */
 export function proratedPaidRefundBase(
-  item: { totalPrice: number; couponDiscountAmount?: number | null; quantity: number },
+  item: {
+    totalPrice: number;
+    couponDiscountAmount?: number | null;
+    /** 주문상품에 배분된 사용 적립금(#93 P3) — 현금 환불 기준에서 뺀다. 없으면 0 */
+    pointAllocation?: number | null;
+    quantity: number;
+  },
   settledQuantity: number,
   cancelQuantity: number,
 ): number {
-  const paid = Math.max(0, item.totalPrice - (item.couponDiscountAmount ?? 0));
+  const paid = Math.max(
+    0,
+    item.totalPrice - (item.couponDiscountAmount ?? 0) - (item.pointAllocation ?? 0),
+  );
   return proratedRefundBase(paid, item.quantity, settledQuantity, cancelQuantity);
 }
+
+/**
+ * 주문상품의 사용 적립금 중 이번 취소 수량의 몫(#93 P3) — 누적 내림의 차분이라 나눠 취소해도 합이 배분액과 같다.
+ * 현금 환불(`proratedPaidRefundBase`)과 따로 돌려준다(`pointRefundAmount`).
+ */
+export function proratedPointRefund(
+  item: { pointAllocation?: number | null; quantity: number },
+  settledQuantity: number,
+  cancelQuantity: number,
+): number {
+  return proratedRefundBase(
+    item.pointAllocation ?? 0,
+    item.quantity,
+    settledQuantity,
+    cancelQuantity,
+  );
+}

package/src/schemas/webhook-event.ts

@@ -58,6 +58,14 @@ export const orderWebhookEventDataSchema = z.object({
       "주문이 받은 상품·주문 쿠폰 할인 합계 (원). 즉시할인(`discountAmount`)과 별개다. " +
         "쿠폰이 없거나 이 필드가 없는 이전 이벤트는 0으로 읽는다",
     ),
+  pointAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "주문에 쓴 적립금 (원, #93). 적립금을 쓰지 않았거나 이 필드가 없는 이전 이벤트는 0으로 읽는다",
+    ),
   orderItemId: z
     .string()
     .optional()
@@ -163,6 +171,15 @@ export const orderCanceledWebhookEventDataSchema = z.object({
       "환불액에 더한 금액 (원) — 앞선 환불에서 뺀 쿠폰 조건 미달 차감을 되돌린 몫이다. " +
         "전량 취소면 누적 차감이 모두 되돌아간다. 이 필드가 없는 이전 이벤트는 0으로 읽는다",
     ),
+  pointRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. " +
+        "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
+    ),
   testPayment: z
     .boolean()
     .describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다"),
@@ -234,6 +251,15 @@ export const claimWebhookEventDataSchema = z.object({
       "환불액에 더한 금액 (원) — 앞선 환불에서 뺀 쿠폰 조건 미달 차감을 되돌린 몫이다. 접수 이벤트는 예상값이다. " +
         "이 필드가 없는 이전 이벤트는 0으로 읽는다",
     ),
+  pointRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. " +
+        "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
+    ),
   testPayment: z
     .boolean()
     .optional()