@sayren/store-sdk 0.28.3 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.28.3",
+  "version": "0.29.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -52,6 +52,20 @@ import {
   type RejectClaimRequest,
   rejectClaimRequestSchema,
 } from "./schemas/claim";
+import {
+  type CollectionCreateRequestInput,
+  type CollectionListParams,
+  type CollectionPatchRequest,
+  type CollectionProductsAddRequest,
+  type CollectionProductsReplaceRequest,
+  collectionCreateRequestSchema,
+  collectionPageSchema,
+  collectionPatchRequestSchema,
+  collectionProductSchema,
+  collectionProductsAddRequestSchema,
+  collectionProductsReplaceRequestSchema,
+  collectionSchema,
+} from "./schemas/collection";
 import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
 import {
   type CreateCouponRequest,
@@ -513,6 +527,50 @@ export function createStoreClient(options: StoreClientOptions) {
         ),
     },
 
+    /**
+     * 컬렉션 (이슈 #83) — 상품을 어디에 보여 줄지 정하는 묶음(다대다). 권한은 카테고리와 같다(`category:r`·`category:rw`).
+     * 쓰기마다 `revision`이 오른다. 수정 본문에 읽은 `revision`을 주면 그 사이 다른 수정이 있을 때 409 `COLLECTION_CHANGED`다.
+     */
+    collections: {
+      list: (params?: CollectionListParams) =>
+        storeHttp.request("GET", "/collections", collectionPageSchema, {
+          query: params as Query,
+        }),
+      get: (collectionId: string) =>
+        storeHttp.request("GET", path`/collections/${collectionId}`, collectionSchema),
+      /** 주소가 겹치면 409 `COLLECTION_SLUG_TAKEN`, 상점당 200개를 넘으면 409 `COLLECTION_LIMIT_EXCEEDED` */
+      create: (body: CollectionCreateRequestInput) =>
+        storeHttp.request("POST", "/collections", collectionSchema, {
+          body: collectionCreateRequestSchema.parse(body),
+        }),
+      update: (collectionId: string, body: CollectionPatchRequest) =>
+        storeHttp.request("PATCH", path`/collections/${collectionId}`, collectionSchema, {
+          body: collectionPatchRequestSchema.parse(body),
+        }),
+      remove: (collectionId: string) =>
+        storeHttp.requestVoid("DELETE", path`/collections/${collectionId}`),
+      /** 담긴 상품 — 직접 정한 순서 */
+      listProducts: (collectionId: string, params?: { page?: number; size?: number }) =>
+        storeHttp.request(
+          "GET",
+          path`/collections/${collectionId}/products`,
+          pageSchema(collectionProductSchema),
+          { query: params as Query },
+        ),
+      /** 담긴 상품을 통째로 바꾼다(순서 포함) */
+      replaceProducts: (collectionId: string, body: CollectionProductsReplaceRequest) =>
+        storeHttp.request("PUT", path`/collections/${collectionId}/products`, collectionSchema, {
+          body: collectionProductsReplaceRequestSchema.parse(body),
+        }),
+      /** 뒤에 붙인다. 이미 담긴 상품은 그 자리에 둔다 */
+      addProducts: (collectionId: string, body: CollectionProductsAddRequest) =>
+        storeHttp.request("POST", path`/collections/${collectionId}/products`, collectionSchema, {
+          body: collectionProductsAddRequestSchema.parse(body),
+        }),
+      removeProduct: (collectionId: string, productId: string) =>
+        storeHttp.requestVoid("DELETE", path`/collections/${collectionId}/products/${productId}`),
+    },
+
     categories: {
       list: (params?: { parentId?: string; flat?: boolean }) =>
         storeHttp.request("GET", "/categories", z.array(categorySchema), {

package/src/index.ts

@@ -22,6 +22,7 @@ export * from "./schemas/audit";
 export * from "./schemas/auth";
 export * from "./schemas/category";
 export * from "./schemas/claim";
+export * from "./schemas/collection";
 export * from "./schemas/common";
 export * from "./schemas/coupon";
 export * from "./schemas/customer";

package/src/schemas/collection.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+import { type PageParams, pageQueryShape, pageSchema } from "./common";
+import { productImageUrlSchema } from "./product";
+
+/**
+ * 컬렉션 (이슈 #83) — 상품을 어디에 보여 줄지 정하는 묶음이다. 카테고리는 상품이 무엇인지를 정하고 상품당 하나지만, 컬렉션은
+ * 다대다다. 이벤트·기획전은 기간이 있는 직접 선택 컬렉션이다. 권한은 카테고리와 같다(`category:r`·`category:rw`).
+ *
+ * 유형은 만들 때 정하고 바꿀 수 없다. 지금은 직접 선택(`MANUAL`)만 만들 수 있다. 조건 자동(`AUTOMATIC`)은 다음 단계에서 열리고,
+ * 응답의 `type`은 값이 늘 수 있어 문자열이다.
+ */
+
+/** 상점당 컬렉션 최대 개수 — 넘으면 409 `COLLECTION_LIMIT_EXCEEDED` */
+export const MAX_COLLECTIONS = 200;
+/** 직접 선택 컬렉션 하나에 담는 상품 최대 개수 — 넘으면 409 `COLLECTION_PRODUCT_LIMIT_EXCEEDED` */
+export const MAX_COLLECTION_PRODUCTS = 1000;
+/** 상품 뒤에 붙이기(`POST /v1/collections/{id}/products`) 한 번에 보내는 상품 최대 개수 */
+export const MAX_COLLECTION_PRODUCTS_PER_ADD = 500;
+/** 제목 최대 글자 수 */
+export const MAX_COLLECTION_TITLE = 60;
+/** 설명 최대 글자 수 */
+export const MAX_COLLECTION_DESCRIPTION = 500;
+/** 주소(slug) 형식 — 영문 소문자·숫자·하이픈, 첫 글자는 영문 소문자나 숫자, 64자까지 */
+export const COLLECTION_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** 유형 — `MANUAL`(직접 선택)·`AUTOMATIC`(조건 자동, 아직 만들 수 없다) */
+export const COLLECTION_TYPES = ["MANUAL", "AUTOMATIC"] as const;
+export type CollectionType = (typeof COLLECTION_TYPES)[number];
+
+/**
+ * 상품 정렬 — `MANUAL`은 직접 정한 순서(직접 선택 컬렉션만)다. `BEST_SELLING`(판매량순)은 판매량 집계가 열릴 때 받는다.
+ * 저장 값 전체 목록이고, 쓰기에서 받는 값은 `collectionProductSortRequestSchema`다.
+ */
+export const COLLECTION_PRODUCT_SORTS = [
+  "MANUAL",
+  "LATEST",
+  "BEST_SELLING",
+  "PRICE_ASC",
+  "PRICE_DESC",
+  "REVIEW_COUNT",
+  "RATING_DESC",
+  "RECOMMEND",
+] as const;
+export type CollectionProductSort = (typeof COLLECTION_PRODUCT_SORTS)[number];
+
+export const collectionProductSortRequestSchema = z
+  .enum(["MANUAL", "LATEST", "PRICE_ASC", "PRICE_DESC", "REVIEW_COUNT", "RATING_DESC", "RECOMMEND"])
+  .describe(
+    "스토어프론트 상품 기본 정렬. `MANUAL`(직접 정한 순서)·`LATEST`(최신순)·`PRICE_ASC`·`PRICE_DESC`·`REVIEW_COUNT`·`RATING_DESC`·`RECOMMEND`(추천순)",
+  );
+
+/** 노출 상태 — 노출 여부와 기간에서 나온 값이다. 숨김이 기간보다 앞선다 */
+export const collectionStateSchema = z.enum(["ACTIVE", "SCHEDULED", "ENDED", "HIDDEN"]);
+export type CollectionState = z.infer<typeof collectionStateSchema>;
+
+/** 노출 상태 판정 — 숨김 → 시작 전(예약) → 종료 → 노출 중. `now`는 판정 시각이다 */
+export function collectionStateOf(
+  collection: { visible: boolean; startsAt: string | null; endsAt: string | null },
+  now: Date,
+): CollectionState {
+  if (!collection.visible) return "HIDDEN";
+  const at = now.getTime();
+  if (collection.startsAt && Date.parse(collection.startsAt) > at) return "SCHEDULED";
+  if (collection.endsAt && Date.parse(collection.endsAt) <= at) return "ENDED";
+  return "ACTIVE";
+}
+
+export const collectionSchema = z.object({
+  collectionId: z.string(),
+  type: z.string().describe("유형. 현재 값은 `MANUAL`·`AUTOMATIC`이고 값이 늘 수 있어 문자열이다"),
+  title: z.string(),
+  slug: z.string().describe("스토어프론트 주소에 쓰는 값. 상점 안에서 유일하다"),
+  description: z.string(),
+  imageUrl: z.string().nullable().describe("대표 이미지 주소"),
+  productSort: z.string().describe("스토어프론트 상품 기본 정렬"),
+  visible: z.boolean().describe("노출 여부. false면 기간과 무관하게 스토어프론트에 보이지 않는다"),
+  startsAt: z.string().nullable().describe("노출 시작 시각. null이면 바로 노출한다"),
+  endsAt: z.string().nullable().describe("노출 종료 시각. null이면 끝나지 않는다"),
+  sortOrder: z.number().int().describe("스토어프론트 컬렉션 목록 순서(작을수록 앞)"),
+  metaTitle: z.string().nullable(),
+  metaDescription: z.string().nullable(),
+  state: collectionStateSchema.describe("지금 노출 상태"),
+  productCount: z.number().int().describe("담긴 상품 수(판매 상태 무관)"),
+  revision: z
+    .number()
+    .int()
+    .describe("수정 번호. 쓰기마다 1씩 오른다. 수정 본문에 주면 그 사이 다른 수정이 있을 때 409다"),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export type Collection = z.infer<typeof collectionSchema>;
+
+const timeField = (description: string) =>
+  z.iso.datetime({ offset: true }).nullable().optional().describe(description);
+
+const slugField = z
+  .string()
+  .regex(COLLECTION_SLUG_PATTERN)
+  .describe(
+    "주소. 영문 소문자·숫자·하이픈 64자까지, 상점 안에서 유일하다(겹치면 409 `COLLECTION_SLUG_TAKEN`)",
+  );
+
+const productIdsField = z
+  .array(z.string().min(1))
+  .max(MAX_COLLECTION_PRODUCTS)
+  .describe("상품 id. 배열 순서가 직접 정한 순서다. 겹치는 id는 처음 것만 남긴다");
+
+const commonFields = {
+  description: z.string().max(MAX_COLLECTION_DESCRIPTION).describe("설명(텍스트)"),
+  imageUrl: productImageUrlSchema.nullable().describe("대표 이미지 주소. https만 받는다"),
+  productSort: collectionProductSortRequestSchema,
+  visible: z.boolean().describe("노출 여부"),
+  startsAt: timeField("노출 시작 시각(ISO 8601, 시간대 포함). null이면 바로 노출한다"),
+  endsAt: timeField("노출 종료 시각(ISO 8601, 시간대 포함). null이면 끝나지 않는다"),
+  sortOrder: z.number().int().min(0).max(1_000_000).describe("목록 순서(작을수록 앞)"),
+  metaTitle: z.string().trim().max(60).nullable().describe("검색 결과 제목"),
+  metaDescription: z.string().trim().max(160).nullable().describe("검색 결과 설명"),
+};
+
+const periodRefine = (
+  body: { startsAt?: string | null; endsAt?: string | null },
+  ctx: z.RefinementCtx,
+) => {
+  if (body.startsAt && body.endsAt && Date.parse(body.endsAt) <= Date.parse(body.startsAt)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["endsAt"],
+      message: "종료 시각은 시작 시각보다 뒤여야 합니다",
+    });
+  }
+};
+
+/**
+ * `POST /v1/collections` — 직접 선택 컬렉션을 만든다. `slug`를 생략하면 `c-{id 뒤 8자}`로 만든다.
+ * `productIds`는 처음 담을 상품과 순서다.
+ */
+export const collectionCreateRequestSchema = z
+  .object({
+    title: z.string().trim().min(1).max(MAX_COLLECTION_TITLE).describe("제목"),
+    slug: slugField.optional(),
+    type: z
+      .enum(["MANUAL"])
+      .default("MANUAL")
+      .describe("유형. 지금은 `MANUAL`(직접 선택)만 받는다. 만든 뒤 바꿀 수 없다"),
+    description: commonFields.description.default(""),
+    imageUrl: commonFields.imageUrl.optional(),
+    productSort: commonFields.productSort.default("MANUAL"),
+    visible: commonFields.visible.default(true),
+    startsAt: commonFields.startsAt,
+    endsAt: commonFields.endsAt,
+    sortOrder: commonFields.sortOrder.optional().describe("목록 순서. 생략하면 맨 뒤"),
+    metaTitle: commonFields.metaTitle.optional(),
+    metaDescription: commonFields.metaDescription.optional(),
+    productIds: productIdsField.optional(),
+  })
+  .superRefine(periodRefine);
+
+export type CollectionCreateRequest = z.infer<typeof collectionCreateRequestSchema>;
+export type CollectionCreateRequestInput = z.input<typeof collectionCreateRequestSchema>;
+
+/**
+ * `PATCH /v1/collections/{collectionId}` — 준 항목만 바뀐다. `type`을 주면 400 `COLLECTION_TYPE_IMMUTABLE`이다.
+ * `revision`을 주면 그 번호일 때만 바뀌고, 그 사이 다른 수정이 있었으면 409 `COLLECTION_CHANGED`다.
+ */
+export const collectionPatchRequestSchema = z
+  .object({
+    title: z.string().trim().min(1).max(MAX_COLLECTION_TITLE).optional(),
+    slug: slugField.optional(),
+    type: z.string().optional().describe("바꿀 수 없다. 주면 400 `COLLECTION_TYPE_IMMUTABLE`"),
+    description: commonFields.description.optional(),
+    imageUrl: commonFields.imageUrl.optional(),
+    productSort: commonFields.productSort.optional(),
+    visible: commonFields.visible.optional(),
+    startsAt: commonFields.startsAt,
+    endsAt: commonFields.endsAt,
+    sortOrder: commonFields.sortOrder.optional(),
+    metaTitle: commonFields.metaTitle.optional(),
+    metaDescription: commonFields.metaDescription.optional(),
+    revision: z.number().int().min(0).optional().describe("읽은 수정 번호"),
+  })
+  .superRefine(periodRefine);
+
+export type CollectionPatchRequest = z.infer<typeof collectionPatchRequestSchema>;
+
+/** `PUT /v1/collections/{collectionId}/products` — 담긴 상품을 통째로 바꾼다(순서 포함) */
+export const collectionProductsReplaceRequestSchema = z.object({
+  productIds: productIdsField,
+  revision: z.number().int().min(0).optional().describe("읽은 수정 번호"),
+});
+
+export type CollectionProductsReplaceRequest = z.infer<
+  typeof collectionProductsReplaceRequestSchema
+>;
+
+/** `POST /v1/collections/{collectionId}/products` — 뒤에 붙인다. 이미 담긴 상품은 그 자리에 둔다 */
+export const collectionProductsAddRequestSchema = z.object({
+  productIds: z.array(z.string().min(1)).min(1).max(MAX_COLLECTION_PRODUCTS_PER_ADD),
+});
+
+export type CollectionProductsAddRequest = z.infer<typeof collectionProductsAddRequestSchema>;
+
+/** 컬렉션에 담긴 상품 한 줄 */
+export const collectionProductSchema = z.object({
+  productId: z.string(),
+  name: z.string(),
+  thumbnailUrl: z.string().nullable(),
+  status: z.string().describe("판매 상태. 스토어프론트에는 `SALE`만 보인다"),
+  salePrice: z.number().int(),
+  position: z.number().int().describe("직접 정한 순서(1부터)"),
+  addedAt: z.string(),
+});
+
+export type CollectionProduct = z.infer<typeof collectionProductSchema>;
+
+export const collectionStateCountsSchema = z.object({
+  ALL: z.number().int(),
+  ACTIVE: z.number().int(),
+  SCHEDULED: z.number().int(),
+  ENDED: z.number().int(),
+  HIDDEN: z.number().int(),
+});
+
+/** 목록 응답 — 페이지 + 상태별 건수(`q`·`type`·`productId`를 적용하고 `state`는 적용하기 전) */
+export const collectionPageSchema = pageSchema(collectionSchema).extend({
+  stateCounts: collectionStateCountsSchema,
+});
+
+export type CollectionPage = z.infer<typeof collectionPageSchema>;
+
+export interface CollectionListParams extends PageParams {
+  q?: string;
+  type?: CollectionType;
+  state?: CollectionState;
+  productId?: string;
+}
+
+/** `GET /v1/collections` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+export const collectionListQuerySchema = z.object({
+  q: z.string().optional().describe("제목·주소 검색(포함, 대소문자 무시)"),
+  type: z.enum(COLLECTION_TYPES).optional().describe("유형"),
+  state: collectionStateSchema.optional().describe("노출 상태"),
+  productId: z.string().optional().describe("이 상품이 담긴 직접 선택 컬렉션만"),
+  ...pageQueryShape({ defaultSize: 20, maxSize: 200 }),
+});
+
+/** `GET /v1/collections/{collectionId}/products` 쿼리 */
+export const collectionProductListQuerySchema = z.object({
+  ...pageQueryShape({ defaultSize: 100, maxSize: MAX_COLLECTION_PRODUCTS }),
+});