@sayren/store-sdk 0.50.0 → 0.52.0

package/src/schemas/coupon.ts

@@ -12,10 +12,12 @@ import {
 import { currencyCodeSchema } from "./currency";
 import {
   COUPON_CONDITIONS_DEFAULTS,
+  COUPON_REWARD_KINDS,
   COUPON_TARGET_LIST_MAX,
   couponBenefitSchema,
   couponConditionsSchema,
   couponKindSchema,
+  couponRewardSchema,
   couponTargetSchema,
 } from "./promotion";
 import { strictRequest } from "./strict";
@@ -35,17 +37,34 @@ export const couponStatusSchema = z
 export type CouponStatus = z.infer<typeof couponStatusSchema>;
 
 /**
- * 발급 방식 — 코드 입력·셀러 지급·다운로드(구매자가 받기)·회원가입 자동 지급(이슈 #110).
+ * 발급 방식 — 코드 입력·셀러 지급·다운로드(구매자가 받기)·회원가입 자동 지급(이슈 #110)·흐름 지급(이슈 #264).
  * 응답(`couponSchema.issueMethod`)은 값이 늘 수 있어 문자열로 받는다. 이 enum은 요청 검증용이다.
  */
 export const couponIssueMethodSchema = z
-  .enum(["CODE", "MANUAL", "DOWNLOAD", "SIGNUP"])
+  .enum(["CODE", "MANUAL", "DOWNLOAD", "SIGNUP", "FLOW", "VOUCHER"])
   .describe(
     "발급 방식. `CODE`=구매자가 주문서에 코드를 입력한다, `MANUAL`=셀러가 회원을 골라 지급한다, " +
-      "`DOWNLOAD`=구매자가 스토어프론트에서 받는다, `SIGNUP`=회원가입 때 자동으로 지급한다",
+      "`DOWNLOAD`=구매자가 스토어프론트에서 받는다, `SIGNUP`=회원가입 때 자동으로 지급한다, " +
+      "`FLOW`=주문 흐름의 쿠폰 지급 단계가 그 주문의 구매자에게 지급한다, " +
+      "`VOUCHER`=셀러가 1회용 쿠폰 번호를 만들어 나눠 주고 구매자가 번호를 등록하면 지급한다",
   );
 export type CouponIssueMethod = z.infer<typeof couponIssueMethodSchema>;
 
+/** 쿠폰 번호 접두어 — 영문·숫자 2~10자, 대문자로 저장한다. 상점 안에서 유일하다 */
+export const VOUCHER_PREFIX_PATTERN = /^[A-Za-z0-9]{2,10}$/;
+/** 쿠폰 번호 한 쿠폰의 최대 개수 */
+export const VOUCHER_COUNT_MAX = 100_000;
+
+/** 쿠폰 번호 설정(`VOUCHER`, 이슈 #264) — 만든 뒤에는 바꿀 수 없다 */
+export const couponVoucherInputSchema = z
+  .strictObject({
+    prefix: z.string().regex(VOUCHER_PREFIX_PATTERN).describe("번호 앞부분(영문·숫자 2~10자)"),
+    count: z.number().int().min(1).max(VOUCHER_COUNT_MAX).describe("만들 번호 수(1~100,000)"),
+  })
+  .describe(
+    "쿠폰 번호 설정 — 1회용 번호 `count`개를 만든다. 번호는 `GET /v1/coupons/{couponId}/voucher-codes`로 받는다",
+  );
+
 /** 코드 형식 — 영문·숫자·`-`·`_` 6~30자. 대소문자를 구분하지 않고 서버가 대문자로 저장한다 */
 export const COUPON_CODE_PATTERN = /^[A-Za-z0-9_-]{6,30}$/;
 
@@ -86,6 +105,9 @@ const descriptions = {
     "발급 대상 트리(이슈 #222) — 셀러 지급·받기·회원가입 지급에서 누가 받을 수 있는가. 구매자 조건만. 코드 입력형에는 두지 않는다",
   stacking:
     "중복 사용 정책(이슈 #222). 생략하면 종류별 한 장·서로 결합·적립금과 함께. 결합은 양쪽 쿠폰이 모두 허용해야 성립한다",
+  reward:
+    "확장 혜택(구간 할인 `TIERED`·N+1 `BUY_X_GET_Y`·적립금 지급 `POINT`). 주면 `benefit`을 생략하고, 응답의 `benefit`은 가장 가까운 값이다. " +
+    "N+1은 상품 쿠폰만, 적립금 지급은 회원 전용 주문 쿠폰만이다. 수정에서 null이면 확장 혜택을 지운다(`benefit`이 필요하다)",
   issueStartsAt: "받기 시작 시각(받기 쿠폰만, 이슈 #222). 생략하면 사용 시작 시각을 따른다",
   issueEndsAt:
     "받기 종료 시각(받기 쿠폰만, 이 시각부터 못 받는다). 생략하면 사용 종료 시각을 따른다",
@@ -99,6 +121,7 @@ const ruleFields = {
   targetRules: couponTargetRulesSchema.optional().describe(descriptions.targetRules),
   audience: couponConditionTreeSchema.optional().describe(descriptions.audience),
   stacking: couponStackingSchema.optional().describe(descriptions.stacking),
+  reward: couponRewardSchema.nullable().optional().describe(descriptions.reward),
 };
 
 /**
@@ -124,6 +147,8 @@ export function couponRequestRuleIssues(body: {
   targetRules?: CouponRuleTrees["targetRules"];
   audience?: CouponRuleTrees["eligibility"];
   stacking?: { perOrderLimit: number };
+  reward?: { type: "TIERED" | "BUY_X_GET_Y" | "POINT" } | null;
+  benefit?: unknown;
   perMemberUseLimit?: number | null;
   dailyIssueLimit?: number | null;
   issueStartsAt?: string | null;
@@ -162,6 +187,27 @@ export function couponRequestRuleIssues(body: {
       ...(body.audience ? { audience: body.audience } : {}),
     }),
   );
+  if (!body.reward && body.benefit === undefined)
+    issues.push({ path: ["benefit"], message: "혜택(benefit 또는 reward)이 필요합니다" });
+  if (
+    body.reward &&
+    body.kind !== undefined &&
+    !(COUPON_REWARD_KINDS[body.reward.type] as readonly string[]).includes(body.kind)
+  )
+    issues.push({
+      path: ["reward", "type"],
+      message:
+        body.reward.type === "POINT"
+          ? "적립금 지급은 주문 쿠폰만 쓸 수 있습니다"
+          : body.reward.type === "BUY_X_GET_Y"
+            ? "N+1은 상품 쿠폰만 쓸 수 있습니다"
+            : "구간 할인은 배송비 쿠폰에 쓸 수 없습니다",
+    });
+  if (body.reward?.type === "POINT" && !conditions.memberOnly)
+    issues.push({
+      path: ["reward", "type"],
+      message: "적립금 지급은 회원 전용 쿠폰만 쓸 수 있습니다",
+    });
   if (body.stacking && body.stacking.perOrderLimit > 1 && body.kind !== "PRODUCT")
     issues.push({
       path: ["stacking", "perOrderLimit"],
@@ -233,13 +279,14 @@ export const createCouponRequestSchema = strictRequest(
       name: z.string().trim().min(1).max(60).describe(descriptions.name),
       description: z.string().max(300).nullable().optional().describe(descriptions.description),
       kind: couponKindSchema,
-      benefit: couponBenefitSchema,
+      benefit: couponBenefitSchema.optional().describe("혜택. `reward`를 주면 생략한다"),
       conditions: couponConditionsInputSchema
         .optional()
         .describe("사용 조건. 생략한 항목은 기본값(최소 금액 0, 회원 전용, 즉시할인과 중복 가능)"),
       target: couponTargetInputSchema.optional().describe("대상 상품·카테고리. 생략하면 전 상품"),
       issueMethod: couponIssueMethodSchema,
       code: z.string().regex(COUPON_CODE_PATTERN).optional().describe(descriptions.code),
+      voucher: couponVoucherInputSchema.optional(),
       startsAt: couponTimeField(descriptions.startsAt),
       endsAt: couponTimeField(descriptions.endsAt),
       validDaysAfterIssue: z
@@ -270,6 +317,12 @@ export const createCouponRequestSchema = strictRequest(
         ctx.addIssue({ code: "custom", path: [path], message });
       if (body.issueMethod === "CODE" && !body.code)
         issue("code", "코드 입력형 쿠폰은 코드가 필요합니다");
+      if (body.reward && body.benefit)
+        issue("benefit", "확장 혜택(reward)을 주면 benefit을 생략합니다");
+      if (body.issueMethod === "VOUCHER" && !body.voucher)
+        issue("voucher", "쿠폰 번호 쿠폰은 번호 설정이 필요합니다");
+      if (body.issueMethod !== "VOUCHER" && body.voucher)
+        issue("voucher", "번호 설정은 쿠폰 번호 쿠폰에만 둡니다");
       if (body.issueMethod !== "CODE" && body.code)
         issue("code", "코드는 코드 입력형 쿠폰에만 둡니다");
       if (body.issueMethod === "CODE" && body.validDaysAfterIssue != null) {
@@ -348,7 +401,7 @@ export const couponSchema = z.object({
   issueMethod: z
     .string()
     .describe(
-      "발급 방식. 현재 값은 `CODE`·`MANUAL`·`DOWNLOAD`(구매자가 받기)·`SIGNUP`(회원가입 자동 지급)이고 값이 추가될 수 있어 문자열로 받는다",
+      "발급 방식. 현재 값은 `CODE`·`MANUAL`·`DOWNLOAD`(구매자가 받기)·`SIGNUP`(회원가입 자동 지급)·`FLOW`(주문 흐름 지급)·`VOUCHER`(쿠폰 번호)이고 값이 추가될 수 있어 문자열로 받는다",
     ),
   code: z.string().nullable().describe("쿠폰 코드(대문자). 코드 입력형이 아니면 null"),
   startsAt: z.string().nullable(),
@@ -365,6 +418,12 @@ export const couponSchema = z.object({
   totalUseLimit: z.number().int().nullable(),
   perMemberIssueLimit: z.number().int().nullable(),
   perMemberUseLimit: z.number().int().nullable(),
+  voucher: z
+    .object({ prefix: z.string(), count: z.number().int() })
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("쿠폰 번호 설정(`VOUCHER`만, 이슈 #264). 다른 발급 방식은 null. 서버는 항상 싣는다"),
   issuedCount: z
     .number()
     .int()
@@ -395,6 +454,11 @@ export const couponSchema = z.object({
     .optional()
     .default(COUPON_STACKING_DEFAULTS)
     .describe("중복 사용 정책(이슈 #222). 서버는 항상 싣는다"),
+  reward: couponRewardSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("확장 혜택. 없으면 null이고 `benefit`이 혜택이다. 서버는 항상 싣는다"),
   rulesOnly: z
     .boolean()
     .optional()
@@ -444,7 +508,7 @@ export const couponIssueSchema = z.object({
     .string()
     .optional()
     .describe(
-      "발급 경로(이슈 #110). 현재 값은 `MANUAL`(셀러 지급)·`DOWNLOAD`(구매자가 받음)·`SIGNUP`(회원가입 자동 지급)이고 값이 추가될 수 있다. 서버는 항상 싣는다",
+      "발급 경로(이슈 #110). 현재 값은 `MANUAL`(셀러 지급)·`DOWNLOAD`(구매자가 받음)·`SIGNUP`(회원가입 자동 지급)·`FLOW`(주문 흐름 지급)·`VOUCHER`(쿠폰 번호 등록)이고 값이 추가될 수 있다. 서버는 항상 싣는다",
     ),
   status: couponIssueStatusSchema,
   validFrom: z.string(),
@@ -460,6 +524,48 @@ export const couponIssueListQuerySchema = z.object({
   ...pageQueryShape(),
 });
 
+/** `GET /v1/coupons/{couponId}/voucher-codes` — 쿠폰 번호 전체(순번 순). 상점 플랫폼이 CSV로 내려받는다 */
+export const couponVoucherCodesSchema = z
+  .object({
+    prefix: z.string(),
+    count: z.number().int(),
+    codes: z.array(z.string()).describe("번호 — 순번 1부터. 등록에 쓴 번호도 싣는다"),
+  })
+  .describe("쿠폰 번호 목록");
+export type CouponVoucherCodes = z.infer<typeof couponVoucherCodesSchema>;
+
+/**
+ * 발급 대상 전원 지급(이슈 #264) — `POST /v1/coupons/{couponId}/distributions`(202)가 만들고 서버가 뒤에서 처리한다. 셀러 지급(`MANUAL`) 쿠폰을
+ * 발급 대상 조건에 맞는 회원 모두에게 준다(셀러 지급과 같은 한도 판정). 쿠폰마다 진행 중 작업은 하나다
+ */
+export const couponDistributionSchema = z
+  .object({
+    distributionId: z.string(),
+    couponId: z.string(),
+    status: z
+      .string()
+      .describe(
+        "작업 상태. 현재 값은 `QUEUED`(대기)·`RUNNING`(지급 중)·`COMPLETED`(끝남)·`FAILED`(실패)이고 값이 추가될 수 있다",
+      ),
+    processedCount: z.number().int().describe("지금까지 살펴본 회원 수"),
+    issuedCount: z.number().int().describe("이 작업이 지급한 장수"),
+    skippedCount: z
+      .number()
+      .int()
+      .describe("건너뛴 회원 수 — 발급 대상이 아니거나 1인 발급 한도에 닿은 회원"),
+    stopCode: z
+      .string()
+      .nullable()
+      .describe(
+        "일찍 끝난 사유. `COUPON_EXHAUSTED`(총 발급 한도)·`COUPON_DAILY_EXHAUSTED`(하루 발급 한도)·`COUPON_NOT_ACTIVE`(중지·종료)·`COUPON_EXPIRED`(사용 기간 끝) 등. 끝까지 돌았으면 null",
+      ),
+    createdAt: z.string(),
+    startedAt: z.string().nullable(),
+    finishedAt: z.string().nullable(),
+  })
+  .describe("발급 대상 전원 지급 작업");
+export type CouponDistribution = z.infer<typeof couponDistributionSchema>;
+
 /** `POST /v1/coupons/{couponId}/issues` — 셀러 지급. 한 번에 1,000명까지 */
 export const issueCouponRequestSchema = z.strictObject({
   customerIds: z

package/src/schemas/customer-delegation.ts

@@ -1,5 +1,6 @@
 import * as z from "zod";
 import { strictRequest } from "./strict";
+import { customerUserinfoInputSchema } from "./userinfo";
 
 /**
  * 구매자 위임 REST(`POST /v1/customers/delegations`, #71) — 계정 토큰(또는 관리 API 토큰) + `X-Store-Id`로 부른다(`customer:rw`).
@@ -31,6 +32,11 @@ export const customerDelegationRequestSchema = strictRequest(
         .describe(
           "사용자가 셀러 서비스에서 실제로 로그인한 시각(uid 위임만). 주면 구매자 토큰의 인증 시각이 된다",
         ),
+      userinfo: customerUserinfoInputSchema
+        .optional()
+        .describe(
+          "OIDC 클레임(이슈 #264) — 위임할 때마다 준 클레임만 바뀌고 null은 지운다. `email_verified`를 생략하면 위임으로 만든 구매자의 이메일은 확인된 것으로 본다",
+        ),
     })
     .refine((value) => Boolean(value.uid || value.email), {
       message: "uid 또는 email이 필요합니다",

package/src/schemas/customer.ts

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import { orderItemStatusSchema, pageQueryShape } from "./common";
 import { strictRequest } from "./strict";
+import { customerUserinfoSchema } from "./userinfo";
 
 /** 구매자 목록 정렬 */
 export const customerSortSchema = z
@@ -169,6 +170,9 @@ export const customerDetailSchema = z.object({
     "약관·개인정보·마케팅 동의의 현재 상태. 이력은 `GET /v1/customers/{customerId}/consents`",
   ),
   addresses: z.array(customerAddressSchema),
+  userinfo: customerUserinfoSchema
+    .optional()
+    .describe("OIDC userinfo 표준 클레임(이슈 #264, 주소는 기본 배송지). 서버는 항상 싣는다"),
   stats: customerStatsSchema.extend({
     canceledOrReturnedCount: z.number().int().describe("취소된 주문 상품 + 완료된 반품 수"),
     reviewCount: z.number().int(),

package/src/schemas/points.ts

@@ -180,6 +180,7 @@ export const POINT_LOT_SOURCES = [
   "ADJUST",
   "REFUND_RESTORE",
   "OPENING",
+  "COUPON",
 ] as const;
 export type PointLotSource = (typeof POINT_LOT_SOURCES)[number];
 
@@ -194,6 +195,7 @@ export const POINT_ENTRY_TYPES = [
   "EXPIRE",
   "ADJUST",
   "OPENING",
+  "EARN_COUPON",
 ] as const;
 export type PointEntryType = (typeof POINT_ENTRY_TYPES)[number];
 
@@ -257,7 +259,7 @@ export const responsePointEntryTypeSchema = z
   .describe(
     "유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · " +
       "`OPENING` 기존 잔액 이전 · `USE_RESERVE` 결제 사용(결제 시작 때 빠짐) · `USE_RELEASE` 결제가 실패·만료되어 되돌림 · " +
-      "`REFUND_RESTORE` 취소·반품 환불로 반환. 값이 추가될 수 있어 문자열로 받는다",
+      "`REFUND_RESTORE` 취소·반품 환불로 반환 · `EARN_COUPON` 적립금 지급 쿠폰. 값이 추가될 수 있어 문자열로 받는다",
   );
 
 /** 원장 항목 — 셀러 조회용(사유·행위자 포함) */
@@ -283,7 +285,7 @@ export const pointLotSchema = z.object({
   lotId: z.string(),
   source: z
     .union([z.enum(POINT_LOT_SOURCES), z.string()])
-    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`REFUND_RESTORE`·`OPENING` 등"),
+    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`REFUND_RESTORE`·`OPENING`·`COUPON` 등"),
   amount: z.number().int().describe("적립한 금액"),
   remaining: z.number().int().describe("남은 금액"),
   expiresAt: z.string().nullable().describe("소멸 시각. null이면 소멸 없음"),