@sayren/storefront-sdk 0.19.0 → 0.20.1

package/dist/payments/index.d.mts

@@ -1,4 +1,4 @@
-import { Bn as CashReceiptRequest, Jn as GuestInfo, cr as ShippingAddressInput, ir as PaymentStatus, lr as StartPaymentRequest, nr as PaymentOption, q as createStorefrontClient, rr as PaymentStart } from "../index-CfOZjg2U.mjs";
+import { dr as PaymentOption, et as createStorefrontClient, fr as PaymentStart, pr as PaymentStatus, qn as CashReceiptRequest, tr as GuestInfo, vr as ShippingAddressInput, yr as StartPaymentRequest } from "../index-q0XQ08--.mjs";
 //#region src/payments/index.d.ts
 /**
  * 스토어프론트 결제 — 브라우저 전용(`@sayren/storefront-sdk/payments`).
@@ -9,6 +9,9 @@ import { Bn as CashReceiptRequest, Jn as GuestInfo, cr as ShippingAddressInput,
  * if (result.status === "COMPLETED") location.assign(`/orders/${result.orderId}`);
  * ```
  *
+ * 결제 금액 전체를 적립금으로 낸 주문은 결제창이 없다. 결제 시작 응답이 `status: "completed"`·`payUrl: null`이면
+ * SDK는 창을 열지 않고(미리 연 팝업은 닫는다) 바로 `COMPLETED`를 돌려준다. 화면 분기는 그대로다.
+ *
  * 결제창은 결제 서비스(`payUrl`)가 그린다. SDK는 그 창을 팝업으로 열고 결과 메시지를 받아 결제 상태 조회로 확정한다.
  * 모바일(또는 `mode: "redirect"`)에서는 현재 탭을 `payUrl`로 보내고, 결제가 끝나면 구매자가 `returnUrl`로 돌아온다 —
  * 복귀 화면에서 {@link Payments.result}를 부른다.
@@ -160,6 +163,8 @@ export interface Payments {
   /**
    * 이미 받은 결제 시작 값으로 결제창만 연다 — 결제 시작을 서버 함수로 하는 SSR 앱용.
    * 클릭 핸들러에서 {@link Payments.prepareWindow}로 창을 먼저 열고 그 핸들을 `window`로 넘긴다.
+   * 결제 시작 값이 `status: "completed"`(결제창 없이 끝난 결제, `payUrl: null`)면 창을 열지 않고 미리 연 창을 닫은 뒤
+   * 바로 `COMPLETED`를 돌려준다. `start`·`retry`도 같다.
    */
   open(start: PaymentStart, options?: {
     mode?: PaymentMode;

package/dist/payments/index.mjs

@@ -1,4 +1,4 @@
-import { v as paymentMessageSchema } from "../checkout-CCsO8PY2.mjs";
+import { y as paymentMessageSchema } from "../checkout-DSAf758s.mjs";
 //#region src/payments/index.ts
 /** 복귀 주소에 결제 서비스가 붙이는 쿼리 */
 const RETURN_PAYMENT_ID = "sayrenPaymentId";
@@ -252,13 +252,34 @@ function createPayments(options) {
 			cancelWatch = cancelThis;
 		});
 	}
+	/** 결제창을 열지 않는 결제 시작 응답의 결과 */
+	async function settleWithoutWindow(start) {
+		if (start.status === "completed" && start.orderId) return {
+			status: "COMPLETED",
+			paymentId: start.paymentId,
+			orderId: start.orderId
+		};
+		try {
+			return paymentResultOf(await client.payments.getStatus(start.paymentId));
+		} catch {
+			return {
+				status: "PROCESSING",
+				paymentId: start.paymentId
+			};
+		}
+	}
 	function open(start, openOptions = {}) {
 		stopWatch();
 		const popup = resolvePrepared(openOptions.window, openOptions.mode).popup;
-		const url = popup ? popupUrl(start.payUrl) : null;
+		const payUrl = start.payUrl;
+		if (start.status !== "pending" || !payUrl) {
+			popup?.close();
+			return settleWithoutWindow(start);
+		}
+		const url = popup ? popupUrl(payUrl) : null;
 		if (!popup || !url) {
 			popup?.close();
-			env.navigate(start.payUrl);
+			env.navigate(payUrl);
 			return new Promise(() => {});
 		}
 		popup.navigate(url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/storefront-sdk",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -91,6 +91,11 @@ import {
   updateProfileRequestSchema,
 } from "./schemas/member";
 import { deliveryTrackingSchema, myOrderSchema } from "./schemas/order";
+import {
+  memberPointEntryPageSchema,
+  memberPointsSchema,
+  storefrontPointPolicySchema,
+} from "./schemas/points";
 import {
   type CreateReviewRequest,
   createReviewRequestSchema,
@@ -248,6 +253,8 @@ export function createStorefrontClient(options: StorefrontClientOptions) {
 
     catalog: {
       listCategories: () => http.request("GET", "/categories", z.array(categoryNodeSchema)),
+      /** `GET /point-policy` — 상점 적립 정책(리뷰·구매 적립, 유효 기간, 리뷰 작성·수정 기한, #93). 리뷰 혜택 안내에 쓴다 */
+      getPointPolicy: () => http.request("GET", "/point-policy", storefrontPointPolicySchema),
       searchProducts: (params?: ProductSearchParams) =>
         http.request("GET", "/products", productPageSchema, { query: params as Query }),
       getProduct: (productId: string) =>
@@ -399,6 +406,13 @@ export function createStorefrontClient(options: StorefrontClientOptions) {
 
     member: {
       me: () => http.request("GET", "/me", memberSchema),
+      /** `GET /me/points` — 내 적립금 잔액과 30일 안 소멸 예정액(#93) */
+      getPoints: () => http.request("GET", "/me/points", memberPointsSchema),
+      /** `GET /me/points/history` — 내 적립금 내역(최신순) */
+      listPointHistory: (params?: PageParams) =>
+        http.request("GET", "/me/points/history", memberPointEntryPageSchema, {
+          query: params as Query,
+        }),
       updateMe: (body: UpdateProfileRequest) =>
         http.requestVoid("PATCH", "/me", { body: updateProfileRequestSchema.parse(body) }),
       /** 약관·개인정보·마케팅 동의의 현재 상태와 재동의 필요 여부 */

package/src/index.ts

@@ -17,6 +17,7 @@ export * from "./schemas/fulfillment";
 export * from "./schemas/inquiry";
 export * from "./schemas/member";
 export * from "./schemas/order";
+export * from "./schemas/points";
 export * from "./schemas/product-options";
 export * from "./schemas/review";
 export * from "./schemas/store";

package/src/payments/index.ts

@@ -19,6 +19,9 @@ import {
  * if (result.status === "COMPLETED") location.assign(`/orders/${result.orderId}`);
  * ```
  *
+ * 결제 금액 전체를 적립금으로 낸 주문은 결제창이 없다. 결제 시작 응답이 `status: "completed"`·`payUrl: null`이면
+ * SDK는 창을 열지 않고(미리 연 팝업은 닫는다) 바로 `COMPLETED`를 돌려준다. 화면 분기는 그대로다.
+ *
  * 결제창은 결제 서비스(`payUrl`)가 그린다. SDK는 그 창을 팝업으로 열고 결과 메시지를 받아 결제 상태 조회로 확정한다.
  * 모바일(또는 `mode: "redirect"`)에서는 현재 탭을 `payUrl`로 보내고, 결제가 끝나면 구매자가 `returnUrl`로 돌아온다 —
  * 복귀 화면에서 {@link Payments.result}를 부른다.
@@ -294,6 +297,8 @@ export interface Payments {
   /**
    * 이미 받은 결제 시작 값으로 결제창만 연다 — 결제 시작을 서버 함수로 하는 SSR 앱용.
    * 클릭 핸들러에서 {@link Payments.prepareWindow}로 창을 먼저 열고 그 핸들을 `window`로 넘긴다.
+   * 결제 시작 값이 `status: "completed"`(결제창 없이 끝난 결제, `payUrl: null`)면 창을 열지 않고 미리 연 창을 닫은 뒤
+   * 바로 `COMPLETED`를 돌려준다. `start`·`retry`도 같다.
    */
   open(
     start: PaymentStart,
@@ -484,6 +489,18 @@ export function createPayments(options: PaymentsOptions): Payments {
     });
   }
 
+  /** 결제창을 열지 않는 결제 시작 응답의 결과 */
+  async function settleWithoutWindow(start: PaymentStart): Promise<PaymentResult> {
+    if (start.status === "completed" && start.orderId) {
+      return { status: "COMPLETED", paymentId: start.paymentId, orderId: start.orderId };
+    }
+    try {
+      return paymentResultOf(await client.payments.getStatus(start.paymentId));
+    } catch {
+      return { status: "PROCESSING", paymentId: start.paymentId };
+    }
+  }
+
   function open(
     start: PaymentStart,
     openOptions: { mode?: PaymentMode; window?: PreparedPaymentWindow } = {},
@@ -492,10 +509,17 @@ export function createPayments(options: PaymentsOptions): Payments {
     stopWatch();
     const prepared = resolvePrepared(openOptions.window, openOptions.mode);
     const popup = prepared.popup;
-    const url = popup ? popupUrl(start.payUrl) : null;
+    const payUrl = start.payUrl;
+    if (start.status !== "pending" || !payUrl) {
+      // 결제창 없이 끝난 결제(적립금 전액 결제, #93)이거나 이 SDK가 모르는 상태다 — 창을 열지 않는다.
+      // 주문 번호가 오면 그대로 완료이고, 아니면 결제 상태 조회로 확정한다(원천은 언제나 `GET /payments/{id}`)
+      popup?.close();
+      return settleWithoutWindow(start);
+    }
+    const url = popup ? popupUrl(payUrl) : null;
     if (!popup || !url) {
       popup?.close();
-      env.navigate(start.payUrl);
+      env.navigate(payUrl);
       // 페이지가 떠난다 — 결과는 복귀 화면의 result()가 읽는다
       return new Promise<PaymentResult>(() => {});
     }

package/src/schemas/checkout.ts

@@ -102,7 +102,35 @@ export const checkoutSessionSchema = z.object({
       .optional()
       .default(0)
       .describe("배송비 쿠폰 할인. 쿠폰이 없으면 0"),
+    pointAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe(
+        "사용 적립금(#93). 주문서는 적립금 전이라 0이고, 결제 시작 응답은 쓴 적립금이다. `totalAmount`는 적립금을 뺀 금액이다",
+      ),
   }),
+  points: z
+    .object({
+      enabled: z
+        .boolean()
+        .describe("이 주문서에서 적립금을 쓸 수 있는가. 비회원·사용 꺼짐이면 false"),
+      balance: z.number().int().describe("내 적립금 잔액"),
+      maxUsable: z
+        .number()
+        .int()
+        .describe(
+          "이 주문서(쿠폰 전, 배송지 반영 전)에서 쓸 수 있는 최대 금액. 쿠폰·배송지를 바꾸면 금액 미리보기로 다시 받는다",
+        ),
+      unit: z.number().int().describe("사용 단위(원)"),
+      minAmount: z.number().int().describe("한 번에 쓰는 최소 금액(원)"),
+      minBalance: z.number().int().describe("쓸 수 있는 최소 보유액(원)"),
+    })
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("적립금 사용 안내(#93). 비회원이거나 상점이 적립금 사용을 끄면 null"),
   delivery: checkoutDeliverySchema.describe(
     "배송비 내역. 배송지를 입력하면 금액이 바뀔 수 있다 — 최종 금액은 결제 시작 응답의 `amounts`다",
   ),
@@ -165,6 +193,20 @@ export const paymentMethodSchema = z.enum([
 
 export type PaymentMethod = z.infer<typeof paymentMethodSchema>;
 
+/**
+ * 응답에 실리는 결제수단 — 아는 값(`PaymentMethod`)이거나 이 SDK가 모르는 새 값(문자열)이다. 서버가 결제수단을 더해도
+ * 응답 파싱이 깨지지 않게 넓게 받는다(`responsePlanCodeSchema`·`easyPayProviderResponseSchema`와 같은 방식, #93 P0).
+ * 적립금 전액 결제 주문은 `POINT`가 온다. 화면은 아는 값으로 분기하고 모르는 값은 그대로 표시하거나 「기타」로 다룬다.
+ * 요청(결제 옵션)은 값을 골라 보내는 자리라 `paymentMethodSchema`(enum) 그대로다.
+ */
+export const responsePaymentMethodSchema = z
+  .union([paymentMethodSchema, z.string()])
+  .describe(
+    "결제수단. `CARD` 카드 · `BANK_TRANSFER` 계좌이체 · `VIRTUAL_ACCOUNT` 가상계좌 · `MOBILE` 휴대폰 · `EASY_PAY` 간편결제 · " +
+      "`POINT` 적립금 전액 결제. 값이 추가될 수 있어 문자열로 받는다",
+  );
+export type ResponsePaymentMethod = PaymentMethod | (string & {});
+
 /** 결제를 처리하는 PG. 셀러가 직접 계약하고 상점 플랫폼 설정 › 결제에서 연결한다 */
 export const pgProviderSchema = z.enum(["tosspayments", "portone"]);
 export type PgProvider = z.infer<typeof pgProviderSchema>;
@@ -398,6 +440,16 @@ export const startPaymentRequestSchema = z.object({
         "적용하지 못하는 쿠폰이 하나라도 있으면 400 `COUPON_NOT_APPLICABLE`(`details`에 사유)이다. 결제가 실패하거나 만료되면 예약이 풀린다. " +
         "쿠폰을 바꾸려면 새로 결제를 시작한다(재시도는 같은 쿠폰을 쓴다)",
     ),
+  pointAmount: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe(
+      "쓸 적립금(#93, 회원만). 결제 시작이 예약하고 쿠폰 뒤 금액에서 뺀다 — 응답 `amounts.pointAmount`가 실제 사용액이다(단위로 내리고 결제 금액 100원을 남긴다). " +
+        "적립금 사용이 꺼져 있으면 409 `POINTS_UNAVAILABLE`, 쓸 수 없으면 400 `POINT_NOT_APPLICABLE`(`details.reason`), 그 사이 잔액이 줄었으면 409 `POINT_BALANCE_CHANGED`다. " +
+        "결제가 실패하거나 만료되면 예약이 풀린다",
+    ),
 });
 
 export type StartPaymentRequest = z.infer<typeof startPaymentRequestSchema>;
@@ -415,14 +467,44 @@ export const retryPaymentRequestSchema = z.object({
 
 export type RetryPaymentRequest = z.infer<typeof retryPaymentRequestSchema>;
 
+/**
+ * 결제 시작 상태 — `pending`이면 `payUrl`로 결제창을 연다. `completed`면 결제창 없이 결제가 끝나 주문이 만들어졌고
+ * `orderId`가 있다(적립금으로 결제 금액 전체를 낸 주문, #93). 값이 추가될 수 있어 응답은 문자열로 받는다.
+ */
+export const PAYMENT_START_STATUS_VALUES = ["pending", "completed"] as const;
+export type KnownPaymentStartStatus = (typeof PAYMENT_START_STATUS_VALUES)[number];
+
 export const paymentStartSchema = z.object({
   paymentId: z.string().describe("결제 id. 상태 조회·재시도의 키다"),
-  attemptId: z.string().describe("결제 시도 id. PG 주문번호(토스 orderId, 포트원 paymentId)다"),
-  option: paymentOptionSchema.describe("이 시도의 결제 옵션"),
+  status: z
+    .string()
+    .optional()
+    .default("pending")
+    .describe(
+      "결제 시작 상태. `pending`이면 `payUrl`로 결제창을 연다. `completed`면 결제창 없이 결제가 끝났고(적립금 전액 결제) `orderId`가 주문 번호다. " +
+        "그 밖의 값은 결제 상태 조회(`GET /payments/{paymentId}`)로 확정한다. 이 필드가 없던 서버 응답은 `pending`으로 읽는다",
+    ),
+  orderId: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("만들어진 주문 번호. `status`가 `completed`일 때만 값이 있고 그 밖에는 null"),
+  attemptId: z
+    .string()
+    .nullable()
+    .describe(
+      "결제 시도 id. PG 주문번호(토스 orderId, 포트원 paymentId)다. 결제창 없이 끝난 결제(`completed`)는 null",
+    ),
+  option: paymentOptionSchema
+    .nullable()
+    .describe("이 시도의 결제 옵션. 결제창 없이 끝난 결제(`completed`)는 null"),
   payUrl: z
     .string()
+    .nullable()
     .describe(
-      "결제 서비스 주소. 팝업으로 열려면 쿼리 `mode=popup`을 붙이고, 그대로 이동하면 리다이렉트 결제다",
+      "결제 서비스 주소. 팝업으로 열려면 쿼리 `mode=popup`을 붙이고, 그대로 이동하면 리다이렉트 결제다. " +
+        "결제창 없이 끝난 결제(`completed`)는 null이다",
     ),
   expiresAt: z.string().describe("결제 요청 만료 시각"),
   testPayment: z

package/src/schemas/claim.ts

@@ -71,6 +71,15 @@ export const createClaimResultSchema = z.object({
       "되돌릴 쿠폰 차감 예상액 — 앞선 취소·반품에서 뺀 쿠폰 조건 미달 차감 중 이번에 돌려받을 몫이다. " +
         "예상 환불액에 이미 반영돼 있다. 서버는 항상 싣는다",
     ),
+  pointRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "돌려받을 적립금 예상액 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 예상 환불액(현금)과 별개다. " +
+        "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문은 0이다. 서버는 항상 싣는다",
+    ),
 });
 
 export type CreateClaimResult = z.infer<typeof createClaimResultSchema>;
@@ -117,6 +126,15 @@ export const myClaimSchema = z.object({
       "예상 배송비 환불액. 배송 묶음이 모두 취소되거나 판매자 귀책일 때만 0보다 크다. " +
         "이 필드가 생기기 전에 접수된 클레임은 null이다",
     ),
+  expectedPointRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "예상 반환 적립금 (원, #93) — 결제에 쓴 적립금 중 이 수량의 몫이다. 예상 환불액(현금)과 별개이고, 차감은 현금에서 먼저 뺀다. " +
+        "교환·적립금을 쓰지 않은 주문은 0이다. 서버는 항상 싣는다",
+    ),
   rejectReason: z.string().nullable(),
   returnAddress: claimReturnAddressSchema
     .nullable()

package/src/schemas/coupon.ts

@@ -96,6 +96,12 @@ export const pricingAmountsSchema = z.object({
   deliveryFee: z.number().int(),
   couponDiscountAmount: z.number().int(),
   deliveryDiscountAmount: z.number().int(),
+  pointAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("사용 적립금(#93). 요청에 `pointAmount`가 없으면 0. 서버는 항상 싣는다"),
   totalAmount: z.number().int().describe("결제 금액"),
 });
 
@@ -107,6 +113,14 @@ export const checkoutPricingRequestSchema = z.object({
     .optional()
     .describe("배송지 우편번호. 주면 제주·도서산간 추가 배송비까지 반영한다"),
   coupons: couponApplicationListSchema,
+  pointAmount: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe(
+      "쓸 적립금(#93, 회원만). 결제 시작과 같은 규칙으로 실제 사용액을 계산한다(예약하지 않는다)",
+    ),
 });
 export type CheckoutPricingRequest = z.infer<typeof checkoutPricingRequestSchema>;
 
@@ -125,9 +139,34 @@ export const checkoutPricingSchema = z.object({
           .optional()
           .describe("주문서 줄의 `lineId`(이슈 #59). 서버는 항상 싣는다"),
         couponDiscountAmount: z.number().int().describe("이 항목에 들어간 쿠폰 할인"),
+        pointAllocation: z
+          .number()
+          .int()
+          .optional()
+          .default(0)
+          .describe("이 항목에 배분한 적립금(#93). 서버는 항상 싣는다"),
       }),
     )
     .describe("주문서 항목별 쿠폰 할인 — 주문서 `items`와 같은 순서"),
+  points: z
+    .object({
+      balance: z.number().int().describe("내 적립금 잔액"),
+      maxUsable: z.number().int().describe("이 금액(쿠폰·배송지 반영)에서 쓸 수 있는 최대 적립금"),
+      adjustReason: z
+        .string()
+        .nullable()
+        .describe("요청보다 적게 쓴 이유. `MIN_PAYMENT`: 결제 금액 100원을 남기려고 줄였다"),
+      rejectReason: z
+        .string()
+        .nullable()
+        .describe(
+          "요청했지만 쓰지 못한 이유 — `MIN_BALANCE`·`MIN_AMOUNT`·`NOT_PAYABLE`. 값이 추가될 수 있다",
+        ),
+    })
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("적립금(#93). 비회원이거나 적립금 사용이 꺼져 있으면 null"),
   payable: z
     .boolean()
     .describe(

package/src/schemas/order.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { easyPayProviderResponseSchema, paymentMethodSchema } from "./checkout";
+import { easyPayProviderResponseSchema, responsePaymentMethodSchema } from "./checkout";
 import { orderItemStatusSchema } from "./common";
 import { myOrderItemFulfillmentSnapshotSchema } from "./fulfillment";
 import { lineSelectionResponseShape } from "./product-options";
@@ -32,6 +32,14 @@ export const myOrderItemSchema = z.object({
     .describe(
       "이 주문상품에 배분된 쿠폰 할인. 실결제 금액은 `totalPrice − couponDiscountAmount`다. 쿠폰이 없으면 0. 서버는 항상 싣는다",
     ),
+  pointAllocation: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "이 주문상품에 쓴 적립금 (원, #93). 현금 실결제는 `totalPrice − couponDiscountAmount − pointAllocation`이다. 적립금을 쓰지 않았으면 0. 서버는 항상 싣는다",
+    ),
   status: orderItemStatusSchema,
   fulfillmentSnapshot: myOrderItemFulfillmentSnapshotSchema.describe(
     "주문 시점 이행 스냅샷(이슈 #57). `type`이 주문 시점 상품 유형이다. 배송 없는 상품(`MANUAL`)이면 `DELIVERED`는 제공 완료다",
@@ -90,8 +98,9 @@ export const myOrderSchema = z.object({
     ),
   shippingAddress: orderShippingAddressSchema,
   payment: z.object({
-    method: paymentMethodSchema.describe(
-      "실제 결제수단(PG가 보고한 수단, 모르면 주문서에서 고른 수단). 결제창에서 바뀔 수 있다(카드 결제창의 간편결제 탭 등)",
+    method: responsePaymentMethodSchema.describe(
+      "실제 결제수단(PG가 보고한 수단, 모르면 주문서에서 고른 수단). 결제창에서 바뀔 수 있다(카드 결제창의 간편결제 탭 등). " +
+        "적립금 전액 결제 주문은 `POINT`다. 값이 추가될 수 있어 문자열로 받는다",
     ),
     easyPayProvider: easyPayProviderResponseSchema
       .nullable()
@@ -114,6 +123,14 @@ export const myOrderSchema = z.object({
       .optional()
       .default(0)
       .describe("배송비 쿠폰 할인. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+    pointAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe(
+        "사용 적립금 (원, #93). `totalAmount`는 적립금을 뺀 결제 금액이다. 적립금을 쓰지 않았으면 0. 서버는 항상 싣는다",
+      ),
     discounts: z
       .array(
         z.object({

package/src/schemas/points.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { pageSchema } from "./common";
+
+/**
+ * 적립금 (이슈 #93) — 상점 적립 정책 안내와 구매자 잔액·내역. 금액은 원 단위 정수다.
+ * 적립금 사용(주문서·결제)은 다음 단계에서 가산한다.
+ */
+
+/** `GET /point-policy` — 상점 적립 정책(인증 없음, 상점 단위). 리뷰 작성·주문 화면의 혜택 안내에 쓴다 */
+export const storefrontPointPolicySchema = z.object({
+  reviewReward: z
+    .object({
+      enabled: z.boolean().describe("리뷰 적립 사용 여부. false면 리뷰 혜택 안내를 그리지 않는다"),
+      textPoint: z.number().int().describe("리뷰를 작성하면 주는 적립금(원)"),
+      photoPoint: z
+        .number()
+        .int()
+        .describe("사진 리뷰에 더 주는 적립금(원). 사진 리뷰는 `textPoint + photoPoint`다"),
+    })
+    .describe("리뷰 적립"),
+  purchaseEarn: z
+    .object({
+      enabled: z.boolean().describe("구매 적립 사용 여부"),
+      rateBp: z
+        .number()
+        .int()
+        .describe("상점 기본 구매 적립률(만분율, 100 = 1%). 상품마다 다를 수 있다"),
+    })
+    .describe("구매 적립 — 구매확정 때 실결제 금액(배송비 제외) × 적립률을 준다"),
+  expiryDays: z.number().int().nullable().describe("적립금 유효 기간(일). 정하지 않았으면 null"),
+  review: z
+    .object({
+      writableDays: z.number().int().describe("구매확정 뒤 리뷰를 쓸 수 있는 기간(일)"),
+      editableDays: z.number().int().describe("리뷰를 쓴 뒤 고칠 수 있는 기간(일)"),
+    })
+    .describe("리뷰 작성·수정 기한"),
+});
+export type StorefrontPointPolicy = z.infer<typeof storefrontPointPolicySchema>;
+
+/** `GET /me/points` — 내 적립금 */
+export const memberPointsSchema = z.object({
+  balance: z.number().int().describe("잔액"),
+  expiringSoon: z.number().int().describe("30일 안에 소멸할 금액"),
+});
+export type MemberPoints = z.infer<typeof memberPointsSchema>;
+
+/** 내 적립금 내역 한 줄 — 셀러 메모는 싣지 않는다 */
+export const memberPointEntrySchema = z.object({
+  entryId: z.string(),
+  type: z
+    .string()
+    .describe(
+      "유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `EXPIRE` 소멸 · `ADJUST` 상점 지급·차감 · " +
+        "`OPENING` 기존 적립금 · `USE_RESERVE` 결제 사용 · `USE_RELEASE` 결제가 실패·만료되어 되돌림 · `REFUND_RESTORE` 취소·반품 환불로 반환. " +
+        "값이 추가될 수 있어 문자열로 받는다",
+    ),
+  amount: z.number().int().describe("변동액. 적립 +, 회수·차감·소멸 −"),
+  balanceAfter: z.number().int().describe("이 변동 직후 잔액"),
+  createdAt: z.string(),
+});
+export type MemberPointEntry = z.infer<typeof memberPointEntrySchema>;
+
+export const memberPointEntryPageSchema = pageSchema(memberPointEntrySchema);