@sayren/store-sdk 0.29.0 → 0.29.2

package/src/client.ts

@@ -56,11 +56,14 @@ import {
   type CollectionCreateRequestInput,
   type CollectionListParams,
   type CollectionPatchRequest,
+  type CollectionPreviewRequest,
   type CollectionProductsAddRequest,
   type CollectionProductsReplaceRequest,
   collectionCreateRequestSchema,
   collectionPageSchema,
   collectionPatchRequestSchema,
+  collectionPreviewRequestSchema,
+  collectionPreviewSchema,
   collectionProductSchema,
   collectionProductsAddRequestSchema,
   collectionProductsReplaceRequestSchema,
@@ -170,6 +173,17 @@ import {
   type VerifyPaymentProviderRequest,
   verifyPaymentProviderRequestSchema,
 } from "./schemas/payment";
+import {
+  customerPointsSchema,
+  type PointAdjustmentRequest,
+  type PointHistoryQuery,
+  pointAdjustmentRequestSchema,
+  pointAdjustmentResultSchema,
+  pointEntrySchema,
+  storePointPolicySchema,
+  type UpdatePointPolicyRequest,
+  updatePointPolicyRequestSchema,
+} from "./schemas/points";
 import {
   type DiscountRequest,
   discountRequestSchema,
@@ -549,7 +563,7 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       remove: (collectionId: string) =>
         storeHttp.requestVoid("DELETE", path`/collections/${collectionId}`),
-      /** 담긴 상품 — 직접 정한 순서 */
+      /** 담긴 상품 — 직접 선택은 정한 순서, 조건 자동은 지금 조건을 만족하는 판매 중 상품(기본 정렬 순) */
       listProducts: (collectionId: string, params?: { page?: number; size?: number }) =>
         storeHttp.request(
           "GET",
@@ -569,6 +583,11 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       removeProduct: (collectionId: string, productId: string) =>
         storeHttp.requestVoid("DELETE", path`/collections/${collectionId}/products/${productId}`),
+      /** 조건 자동 미리보기 — 저장하지 않고 조건을 만족하는 판매 중 상품 수와 앞 20개를 본다 */
+      preview: (body: CollectionPreviewRequest) =>
+        storeHttp.request("POST", "/collections/preview", collectionPreviewSchema, {
+          body: collectionPreviewRequestSchema.parse(body),
+        }),
     },
 
     categories: {
@@ -800,7 +819,41 @@ export function createStoreClient(options: StoreClientOptions) {
     },
 
     /** 구매자 관리 — 조회 `customer:r`, 탈퇴 처리 `customer:rw`(상점 플랫폼 OWNER·ADMIN) */
+    /** 적립금 — 상점 전체 원장(#93). 스코프 `promotion:r` */
+    points: {
+      /** `GET /v1/points/history` — 회원(`memberId`)·유형(`type`)·기간(`from`·`to`)으로 거른다 */
+      listHistory: (params?: PointHistoryQuery) =>
+        storeHttp.request("GET", "/points/history", pageSchema(pointEntrySchema), {
+          query: params as Query,
+        }),
+    },
+
     customers: {
+      /** `GET /v1/customers/{customerId}/points` — 잔액·30일 안 소멸 예정·남은 적립 묶음(#93) */
+      getPoints: (customerId: string) =>
+        storeHttp.request("GET", path`/customers/${customerId}/points`, customerPointsSchema),
+      /** `GET /v1/customers/{customerId}/points/history` — 적립금 내역(최신순, 셀러 사유 포함) */
+      listPointHistory: (customerId: string, params?: Omit<PointHistoryQuery, "memberId">) =>
+        storeHttp.request(
+          "GET",
+          path`/customers/${customerId}/points/history`,
+          pageSchema(pointEntrySchema),
+          { query: params as Query },
+        ),
+      /**
+       * `POST /v1/customers/{customerId}/points/adjustments` (201) — 스코프 `promotion:rw`. 양수 지급, 음수 차감. `idempotencyKey`가 필수다.
+       * 에러: 409 `POINT_BALANCE_INSUFFICIENT`·`POINTS_UNAVAILABLE`, 400 `POINT_EXPIRY_REQUIRED`. 에이전트 요청은 승인 대상이다
+       */
+      adjustPoints: (customerId: string, body: PointAdjustmentRequest, idempotencyKey: string) =>
+        storeHttp.request(
+          "POST",
+          path`/customers/${customerId}/points/adjustments`,
+          pointAdjustmentResultSchema,
+          {
+            body: pointAdjustmentRequestSchema.parse(body),
+            headers: idempotency(idempotencyKey),
+          },
+        ),
       list: (
         params?: PageParams & Omit<z.input<typeof customerListQuerySchema>, "page" | "size">,
       ) =>
@@ -1553,6 +1606,19 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("PATCH", "/store", storeSchema, {
           body: updateStoreRequestSchema.parse(body),
         }),
+      /**
+       * `GET /v1/store/point-policy` — 스코프 `promotion:r`. 적립금 정책(리뷰 적립·유효 기간)과 준비 여부(`available`), 상점에 보일 안내(`notice`).
+       * 정책을 정하지 않았으면 모두 끔이다(#93)
+       */
+      getPointPolicy: () => storeHttp.request("GET", "/store/point-policy", storePointPolicySchema),
+      /**
+       * `PUT /v1/store/point-policy` — 스코프 `promotion:rw`. 준 항목만 바꾼다. 에이전트 요청은 승인 대상이다.
+       * 에러: 409 `POINTS_UNAVAILABLE`(준비 중) · 400 `POINT_EXPIRY_REQUIRED`(리뷰 적립을 켜는데 유효 기간이 없음)
+       */
+      updatePointPolicy: (body: UpdatePointPolicyRequest) =>
+        storeHttp.request("PUT", "/store/point-policy", storePointPolicySchema, {
+          body: updatePointPolicyRequestSchema.parse(body),
+        }),
       listMembers: () => storeHttp.request("GET", "/store/members", z.array(storeMemberSchema)),
       /** `PATCH /v1/store/members/{userId}` — 스코프 `member:rw`. OWNER는 바꿀 수 없고 ADMIN 지정·ADMIN 변경은 OWNER만 한다 */
       updateMemberRole: (userId: string, body: UpdateMemberRoleRequest) =>

package/src/index.ts

@@ -32,6 +32,7 @@ export * from "./schemas/login";
 export * from "./schemas/misc";
 export * from "./schemas/order";
 export * from "./schemas/payment";
+export * from "./schemas/points";
 export * from "./schemas/product";
 export * from "./schemas/promotion";
 export * from "./schemas/refund-policy";

package/src/schemas/collection.ts

@@ -6,8 +6,8 @@ import { productImageUrlSchema } from "./product";
  * 컬렉션 (이슈 #83) — 상품을 어디에 보여 줄지 정하는 묶음이다. 카테고리는 상품이 무엇인지를 정하고 상품당 하나지만, 컬렉션은
  * 다대다다. 이벤트·기획전은 기간이 있는 직접 선택 컬렉션이다. 권한은 카테고리와 같다(`category:r`·`category:rw`).
  *
- * 유형은 만들 때 정하고 바꿀 수 없다. 지금은 직접 선택(`MANUAL`)만 만들 수 있다. 조건 자동(`AUTOMATIC`)은 다음 단계에서 열리고,
- * 응답의 `type`은 값이 늘 수 있어 문자열이다.
+ * 유형은 만들 때 정하고 바꿀 수 없다. 직접 선택(`MANUAL`)은 셀러가 상품을 담고 순서를 정하고, 조건 자동(`AUTOMATIC`)은 조건(`rules`)을
+ * 모두 만족하는 판매 중 상품을 조회할 때마다 계산한다(결과를 저장하지 않는다). 응답의 `type`은 값이 늘 수 있어 문자열이다.
  */
 
 /** 상점당 컬렉션 최대 개수 — 넘으면 409 `COLLECTION_LIMIT_EXCEEDED` */
@@ -23,7 +23,7 @@ export const MAX_COLLECTION_DESCRIPTION = 500;
 /** 주소(slug) 형식 — 영문 소문자·숫자·하이픈, 첫 글자는 영문 소문자나 숫자, 64자까지 */
 export const COLLECTION_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 
-/** 유형 — `MANUAL`(직접 선택)·`AUTOMATIC`(조건 자동, 아직 만들 수 없다) */
+/** 유형 — `MANUAL`(직접 선택)·`AUTOMATIC`(조건 자동) */
 export const COLLECTION_TYPES = ["MANUAL", "AUTOMATIC"] as const;
 export type CollectionType = (typeof COLLECTION_TYPES)[number];
 
@@ -65,6 +65,210 @@ export function collectionStateOf(
   return "ACTIVE";
 }
 
+/** 조건 자동 컬렉션의 조건 최대 개수 */
+export const MAX_COLLECTION_RULES = 10;
+/** 카테고리 조건 하나에 넣는 카테고리 최대 개수 */
+export const MAX_COLLECTION_RULE_CATEGORIES = 20;
+/** 등록일 조건의 최대 일수 */
+export const MAX_COLLECTION_CREATED_WITHIN_DAYS = 365;
+/** 미리보기(`POST /v1/collections/preview`)가 싣는 상품 최대 개수 */
+export const COLLECTION_PREVIEW_SIZE = 20;
+
+const createdWithinDaysRuleSchema = z.object({
+  field: z.literal("createdWithinDays"),
+  value: z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_COLLECTION_CREATED_WITHIN_DAYS)
+    .describe("등록한 지 N일 안의 상품(1~365). 조회 시각에서 N일을 뺀 시각 이후에 등록한 상품이다"),
+});
+
+const categoryRuleSchema = z.object({
+  field: z.literal("category"),
+  categoryIds: z
+    .array(z.string().min(1))
+    .min(1)
+    .max(MAX_COLLECTION_RULE_CATEGORIES)
+    .describe(
+      "카테고리 id(1~20개). 하위 카테고리의 상품도 포함한다. 상점에 없는 id는 400 `COLLECTION_CATEGORY_NOT_FOUND`다",
+    ),
+});
+
+const priceRuleSchema = z.object({
+  field: z.literal("price"),
+  min: z.number().int().min(0).optional().describe("최저가(포함, 원)"),
+  max: z.number().int().min(0).optional().describe("최고가(포함, 원)"),
+});
+
+const discountedRuleSchema = z.object({
+  field: z.literal("discounted"),
+  value: z.literal(true).describe("즉시할인이 지금 적용되는 상품"),
+});
+
+/**
+ * 조건 하나 — `field`로 가른다. 가격은 즉시할인을 반영한 판매가(`discountedPrice ?? salePrice`)다.
+ * 판매량 상위(`bestSelling`)는 판매량 집계가 열릴 때 더한다.
+ */
+export const collectionRuleSchema = z
+  .discriminatedUnion("field", [
+    createdWithinDaysRuleSchema,
+    categoryRuleSchema,
+    priceRuleSchema,
+    discountedRuleSchema,
+  ])
+  .superRefine((rule, ctx) => {
+    if (rule.field !== "price") return;
+    if (rule.min === undefined && rule.max === undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["min"],
+        message: "최저가나 최고가 중 하나는 있어야 합니다",
+      });
+    } else if (rule.min !== undefined && rule.max !== undefined && rule.min > rule.max) {
+      ctx.addIssue({ code: "custom", path: ["max"], message: "최고가는 최저가 이상이어야 합니다" });
+    }
+  });
+
+export type CollectionRule = z.infer<typeof collectionRuleSchema>;
+export type CollectionRuleField = CollectionRule["field"];
+
+/** 조건 목록 — 모두 만족해야 한다(AND). 같은 `field`는 한 번만 쓴다 */
+export const collectionRulesSchema = z
+  .array(collectionRuleSchema)
+  .min(1)
+  .max(MAX_COLLECTION_RULES)
+  .superRefine((rules, ctx) => {
+    const seen = new Set<string>();
+    rules.forEach((rule, index) => {
+      if (seen.has(rule.field)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [index, "field"],
+          message: "같은 조건을 두 번 쓸 수 없습니다",
+        });
+      }
+      seen.add(rule.field);
+    });
+  })
+  .describe(
+    "조건 목록. 모두 만족하는 판매 중 상품이 컬렉션 상품이다(AND). 같은 조건(`field`)은 한 번만 쓴다",
+  );
+
+/**
+ * 응답의 조건 — 이 SDK가 아는 조건이거나 뒤에 더해질 조건(`field`만 확인한다)이다. 새 조건이 생겨도 옛 SDK의 응답 검증이 깨지지 않는다.
+ */
+export const collectionRuleViewSchema = z.union([
+  createdWithinDaysRuleSchema,
+  categoryRuleSchema,
+  priceRuleSchema,
+  discountedRuleSchema,
+  z.looseObject({ field: z.string() }),
+]);
+
+export type CollectionRuleView = z.infer<typeof collectionRuleViewSchema>;
+
+/** 조건 판정에 쓰는 상품 값 — 즉시할인가는 호출부가 계산해 넘긴다 */
+export interface CollectionRuleProduct {
+  createdAt: string;
+  categoryId: string | null;
+  salePrice: number;
+  /** 지금 적용되는 즉시할인가. 할인이 없으면 null */
+  discountedPrice: number | null;
+}
+
+export interface CollectionRuleContext {
+  /** 판정 시각 — 등록일 조건의 기준이다 */
+  now: Date;
+  /** 상점 카테고리(부모 관계) — 카테고리 조건의 하위 포함 판정에 쓴다 */
+  categories: ReadonlyArray<{ categoryId: string; parentId: string | null }>;
+}
+
+const DAY_MS = 86_400_000;
+
+/** 카테고리 자신 + 모든 하위 카테고리 id */
+export function descendantCategoryIdsOf(
+  roots: readonly string[],
+  categories: CollectionRuleContext["categories"],
+): Set<string> {
+  const ids = new Set(roots);
+  const children = new Map<string, string[]>();
+  for (const category of categories) {
+    if (!category.parentId) continue;
+    const list = children.get(category.parentId);
+    if (list) list.push(category.categoryId);
+    else children.set(category.parentId, [category.categoryId]);
+  }
+  const queue = [...roots];
+  for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+    for (const child of children.get(next) ?? []) {
+      if (ids.has(child)) continue;
+      ids.add(child);
+      queue.push(child);
+    }
+  }
+  return ids;
+}
+
+/**
+ * 조건 판정 함수를 만든다 — 모든 조건을 만족해야 true다(AND). 카테고리 트리는 여기서 한 번만 푼다.
+ * 알 수 없는 조건(`field`)은 만족하지 않는 것으로 본다. 모르는 조건을 건너뛰면 상품이 예고 없이 늘어난다.
+ * 판매 상태는 보지 않는다. 판매 중만 거르는 것은 호출부다.
+ */
+export function collectionRulesPredicate(
+  rules: readonly CollectionRuleView[],
+  context: CollectionRuleContext,
+): (product: CollectionRuleProduct) => boolean {
+  const checks = rules.map((rule): ((product: CollectionRuleProduct) => boolean) => {
+    const known = collectionRuleSchema.safeParse(rule);
+    if (!known.success) return () => false;
+    const parsed = known.data;
+    switch (parsed.field) {
+      case "createdWithinDays": {
+        const since = context.now.getTime() - parsed.value * DAY_MS;
+        return (product) => Date.parse(product.createdAt) >= since;
+      }
+      case "category": {
+        const ids = descendantCategoryIdsOf(parsed.categoryIds, context.categories);
+        return (product) => product.categoryId !== null && ids.has(product.categoryId);
+      }
+      case "price":
+        return (product) => {
+          const price = product.discountedPrice ?? product.salePrice;
+          return (
+            (parsed.min === undefined || price >= parsed.min) &&
+            (parsed.max === undefined || price <= parsed.max)
+          );
+        };
+      case "discounted":
+        return (product) =>
+          product.discountedPrice !== null && product.discountedPrice < product.salePrice;
+      default:
+        return () => false;
+    }
+  });
+  return (product) => checks.length > 0 && checks.every((check) => check(product));
+}
+
+/** 상품 하나가 조건을 모두 만족하는가 — 여러 상품을 판정할 때는 `collectionRulesPredicate`를 한 번 만들어 쓴다 */
+export function matchesCollectionRules(
+  product: CollectionRuleProduct,
+  rules: readonly CollectionRuleView[],
+  context: CollectionRuleContext,
+): boolean {
+  return collectionRulesPredicate(rules, context)(product);
+}
+
+/** 조건이 참조하는 카테고리 id — 카테고리 삭제의 참조 검사에 쓴다 */
+export function collectionRuleCategoryIds(rules: readonly CollectionRuleView[]): string[] {
+  const ids: string[] = [];
+  for (const rule of rules) {
+    const parsed = categoryRuleSchema.safeParse(rule);
+    if (parsed.success) ids.push(...parsed.data.categoryIds);
+  }
+  return ids;
+}
+
 export const collectionSchema = z.object({
   collectionId: z.string(),
   type: z.string().describe("유형. 현재 값은 `MANUAL`·`AUTOMATIC`이고 값이 늘 수 있어 문자열이다"),
@@ -73,6 +277,10 @@ export const collectionSchema = z.object({
   description: z.string(),
   imageUrl: z.string().nullable().describe("대표 이미지 주소"),
   productSort: z.string().describe("스토어프론트 상품 기본 정렬"),
+  rules: z
+    .array(collectionRuleViewSchema)
+    .nullable()
+    .describe("조건 자동 컬렉션의 조건(AND). 직접 선택 컬렉션은 null"),
   visible: z.boolean().describe("노출 여부. false면 기간과 무관하게 스토어프론트에 보이지 않는다"),
   startsAt: z.string().nullable().describe("노출 시작 시각. null이면 바로 노출한다"),
   endsAt: z.string().nullable().describe("노출 종료 시각. null이면 끝나지 않는다"),
@@ -80,7 +288,12 @@ export const collectionSchema = z.object({
   metaTitle: z.string().nullable(),
   metaDescription: z.string().nullable(),
   state: collectionStateSchema.describe("지금 노출 상태"),
-  productCount: z.number().int().describe("담긴 상품 수(판매 상태 무관)"),
+  productCount: z
+    .number()
+    .int()
+    .describe(
+      "상품 수. 직접 선택은 담긴 상품 수(판매 상태 무관), 조건 자동은 지금 조건을 만족하는 판매 중 상품 수",
+    ),
   revision: z
     .number()
     .int()
@@ -132,20 +345,28 @@ const periodRefine = (
 };
 
 /**
- * `POST /v1/collections` — 직접 선택 컬렉션을 만든다. `slug`를 생략하면 `c-{id 뒤 8자}`로 만든다.
- * `productIds`는 처음 담을 상품과 순서다.
+ * `POST /v1/collections` — 컬렉션을 만든다. `slug`를 생략하면 `c-{id 뒤 8자}`로 만든다.
+ * 직접 선택(`MANUAL`)은 `productIds`가 처음 담을 상품과 순서다. 조건 자동(`AUTOMATIC`)은 `rules`가 있어야 하고 `productIds`를 받지 않는다.
+ * `productSort`를 생략하면 직접 선택은 `MANUAL`, 조건 자동은 `LATEST`다. 조건 자동은 `MANUAL`을 쓸 수 없다.
  */
 export const collectionCreateRequestSchema = z
   .object({
     title: z.string().trim().min(1).max(MAX_COLLECTION_TITLE).describe("제목"),
     slug: slugField.optional(),
     type: z
-      .enum(["MANUAL"])
+      .enum(COLLECTION_TYPES)
       .default("MANUAL")
-      .describe("유형. 지금은 `MANUAL`(직접 선택)만 받는다. 만든 뒤 바꿀 수 없다"),
+      .describe("유형. `MANUAL`(직접 선택)·`AUTOMATIC`(조건 자동). 만든 뒤 바꿀 수 없다"),
+    rules: collectionRulesSchema
+      .optional()
+      .describe("조건 자동 컬렉션의 조건(AND). 조건 자동이면 필수, 직접 선택이면 줄 수 없다"),
     description: commonFields.description.default(""),
     imageUrl: commonFields.imageUrl.optional(),
-    productSort: commonFields.productSort.default("MANUAL"),
+    productSort: commonFields.productSort
+      .optional()
+      .describe(
+        "스토어프론트 상품 기본 정렬. 생략하면 직접 선택은 `MANUAL`, 조건 자동은 `LATEST`다. 조건 자동은 `MANUAL`을 쓸 수 없다",
+      ),
     visible: commonFields.visible.default(true),
     startsAt: commonFields.startsAt,
     endsAt: commonFields.endsAt,
@@ -168,6 +389,11 @@ export const collectionPatchRequestSchema = z
     title: z.string().trim().min(1).max(MAX_COLLECTION_TITLE).optional(),
     slug: slugField.optional(),
     type: z.string().optional().describe("바꿀 수 없다. 주면 400 `COLLECTION_TYPE_IMMUTABLE`"),
+    rules: collectionRulesSchema
+      .optional()
+      .describe(
+        "조건 자동 컬렉션의 조건을 통째로 바꾼다. 직접 선택 컬렉션에 주면 400 `COLLECTION_RULES_NOT_ALLOWED`",
+      ),
     description: commonFields.description.optional(),
     imageUrl: commonFields.imageUrl.optional(),
     productSort: commonFields.productSort.optional(),
@@ -207,8 +433,11 @@ export const collectionProductSchema = z.object({
   thumbnailUrl: z.string().nullable(),
   status: z.string().describe("판매 상태. 스토어프론트에는 `SALE`만 보인다"),
   salePrice: z.number().int(),
-  position: z.number().int().describe("직접 정한 순서(1부터)"),
-  addedAt: z.string(),
+  position: z
+    .number()
+    .int()
+    .describe("순서(1부터). 직접 선택은 셀러가 정한 순서, 조건 자동은 컬렉션 기본 정렬의 순위"),
+  addedAt: z.string().describe("담은 시각. 조건 자동은 상품 등록 시각"),
 });
 
 export type CollectionProduct = z.infer<typeof collectionProductSchema>;
@@ -248,3 +477,21 @@ export const collectionListQuerySchema = z.object({
 export const collectionProductListQuerySchema = z.object({
   ...pageQueryShape({ defaultSize: 100, maxSize: MAX_COLLECTION_PRODUCTS }),
 });
+
+/** `POST /v1/collections/preview` — 저장하지 않고 조건으로 나오는 상품을 본다 */
+export const collectionPreviewRequestSchema = z.object({
+  rules: collectionRulesSchema,
+  productSort: collectionProductSortRequestSchema
+    .optional()
+    .describe("미리보기 순서. 생략하거나 `MANUAL`이면 `LATEST`다"),
+});
+
+export type CollectionPreviewRequest = z.infer<typeof collectionPreviewRequestSchema>;
+
+/** 미리보기 응답 — 조건을 만족하는 판매 중 상품 수와 앞 20개 */
+export const collectionPreviewSchema = z.object({
+  count: z.number().int().describe("조건을 만족하는 판매 중 상품 수(조회 시각 기준)"),
+  products: z.array(collectionProductSchema).describe("앞 20개(정렬 순)"),
+});
+
+export type CollectionPreview = z.infer<typeof collectionPreviewSchema>;