@sayren/store-sdk 0.50.0 → 0.51.0

package/src/schemas/coupon.ts

@@ -35,17 +35,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}$/;
 
@@ -240,6 +257,7 @@ export const createCouponRequestSchema = strictRequest(
       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 +288,10 @@ export const createCouponRequestSchema = strictRequest(
         ctx.addIssue({ code: "custom", path: [path], message });
       if (body.issueMethod === "CODE" && !body.code)
         issue("code", "코드 입력형 쿠폰은 코드가 필요합니다");
+      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 +370,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 +387,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()
@@ -444,7 +472,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 +488,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/userinfo.ts

@@ -0,0 +1,118 @@
+import * as z from "zod";
+
+/**
+ * 구매자 정보의 OIDC userinfo 표준 클레임(OpenID Connect Core 1.0 5.1, 이슈 #264). 이름은 표준 그대로 snake_case다.
+ * 값이 없는 클레임은 응답에서 빠진다. 같은 형식이 스토어프론트 API(storefront-sdk `userinfoSchema`)에도 있다.
+ */
+
+/** 생일 — `YYYY-MM-DD`, 연도를 모르면 `0000-MM-DD`(표준 형식) */
+export const CUSTOMER_BIRTHDATE_PATTERN = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;
+
+export const customerUserinfoAddressSchema = z.object({
+  formatted: z.string().optional(),
+  street_address: z.string().optional(),
+  locality: z.string().optional(),
+  region: z.string().optional(),
+  postal_code: z.string().optional(),
+  country: z.string().optional().describe("ISO 3166-1 alpha-2"),
+});
+
+export const customerUserinfoSchema = z
+  .object({
+    sub: z.string().describe("구매자 id(상점 안에서 유일)"),
+    name: z.string().optional(),
+    given_name: z.string().optional(),
+    family_name: z.string().optional(),
+    middle_name: z.string().optional(),
+    nickname: z.string().optional(),
+    preferred_username: z.string().optional(),
+    profile: z.string().optional(),
+    picture: z.string().optional(),
+    website: z.string().optional(),
+    email: z.string().optional(),
+    email_verified: z
+      .boolean()
+      .optional()
+      .describe("이메일 확인 여부 — 인증된 소셜 가입·셀러 위임만 true다. 비밀번호 가입은 false"),
+    gender: z.string().optional().describe("표준 값은 `female`·`male`이고 다른 값도 온다"),
+    birthdate: z.string().optional().describe("`YYYY-MM-DD`, 연도를 모르면 `0000-MM-DD`"),
+    zoneinfo: z.string().optional().describe("IANA 시간대(예: `Asia/Seoul`)"),
+    locale: z.string().optional().describe("BCP 47 언어 태그(예: `ko-KR`)"),
+    phone_number: z.string().optional().describe("E.164(예: `+821012345678`)"),
+    phone_number_verified: z.boolean().optional(),
+    address: customerUserinfoAddressSchema.optional().describe("기본 배송지에서 만든다"),
+    updated_at: z.number().int().optional().describe("프로필을 바꾼 시각(epoch 초)"),
+  })
+  .describe("OIDC userinfo 표준 클레임(이슈 #264)");
+export type CustomerUserinfo = z.infer<typeof customerUserinfoSchema>;
+
+const text = (max: number) => z.string().trim().min(1).max(max).nullable().optional();
+const httpsUrl = z
+  .url({ protocol: /^https$/ })
+  .max(2048)
+  .nullable()
+  .optional()
+  .describe("https 주소");
+
+/** 시간대·언어 태그 검사 — 런타임(Intl)이 아는 값만 받는다 */
+const zoneinfo = z
+  .string()
+  .max(64)
+  .refine((value) => {
+    try {
+      new Intl.DateTimeFormat("en", { timeZone: value });
+      return true;
+    } catch {
+      return false;
+    }
+  }, "IANA 시간대가 아닙니다")
+  .nullable()
+  .optional();
+const locale = z
+  .string()
+  .max(35)
+  .refine((value) => {
+    try {
+      return Intl.getCanonicalLocales(value).length === 1;
+    } catch {
+      return false;
+    }
+  }, "BCP 47 언어 태그가 아닙니다")
+  .nullable()
+  .optional();
+const birthdate = z
+  .string()
+  .regex(CUSTOMER_BIRTHDATE_PATTERN, "생일은 YYYY-MM-DD(연도를 모르면 0000-MM-DD)입니다")
+  .refine((value) => {
+    const [y, m, d] = value.split("-").map(Number) as [number, number, number];
+    // 연도를 모르면 윤년(2000)으로 날짜만 본다
+    const day = new Date(Date.UTC(y === 0 ? 2000 : y, m - 1, d));
+    return day.getUTCMonth() === m - 1 && day.getUTCDate() === d;
+  }, "없는 날짜입니다")
+  .nullable()
+  .optional();
+
+/**
+ * 셀러가 위임으로 바꿀 수 있는 클레임 — 준 클레임만 바뀌고 null은 지운다. `sub`·`email`·`phone_number`·`updated_at`·`address`는 받지 않는다. 확인 여부(`*_verified`)는 셀러가 확인한 값을 받는다
+ * (이메일·휴대폰은 각자의 칸, 주소는 배송지가 원천이다)
+ */
+export const customerUserinfoInputSchema = z
+  .strictObject({
+    /** 셀러가 확인한 값 그대로 받는다 — 셀러 서비스가 인증한 회원이다 */
+    email_verified: z.boolean().optional(),
+    phone_number_verified: z.boolean().optional(),
+    given_name: text(50),
+    family_name: text(50),
+    middle_name: text(50),
+    nickname: text(50),
+    preferred_username: text(50),
+    profile: httpsUrl,
+    picture: httpsUrl,
+    website: httpsUrl,
+    gender: text(30),
+    birthdate,
+    zoneinfo,
+    locale,
+  })
+  .describe("바꿀 OIDC 클레임 — 준 것만 바뀌고 null은 지운다");
+export type CustomerUserinfoInput = z.infer<typeof customerUserinfoInputSchema>;

package/dist/webhook-headers-D6QmPdEJ.d.mts

@@ -1,22 +0,0 @@
-//#region src/webhook-headers.d.ts
-/** 웹훅 발송 요청 헤더 상수 (공개 계약). zod 의존 없이 서버 엔트리포인트에서도 가볍게 쓴다 */
-/** 서명 헤더. 형식: `t=<unix초>,v1=<hex>[,v1=<hex>]` */
-declare const WEBHOOK_SIGNATURE_HEADER = "Sayren-Signature";
-/** 이벤트 ID 헤더. 본문 `id`와 같다. 중복 제거 키 */
-declare const WEBHOOK_EVENT_ID_HEADER = "Sayren-Event-Id";
-/** 이벤트 타입 헤더. 본문 `type`과 같다 */
-declare const WEBHOOK_EVENT_TYPE_HEADER = "Sayren-Event-Type";
-/** 전송 기록 ID 헤더. 전송 기록의 `deliveryId`와 같다 */
-declare const WEBHOOK_DELIVERY_ID_HEADER = "Sayren-Delivery-Id";
-/** 발송 요청의 `User-Agent` 값 */
-declare const WEBHOOK_USER_AGENT = "Sayren-Webhooks/1.0";
-/** 수신 측 권장 타임스탬프 허용 오차(초) */
-declare const WEBHOOK_DEFAULT_TOLERANCE_SEC = 300;
-declare const WEBHOOK_HEADERS: {
-  readonly signature: "Sayren-Signature";
-  readonly eventId: "Sayren-Event-Id";
-  readonly eventType: "Sayren-Event-Type";
-  readonly deliveryId: "Sayren-Delivery-Id";
-};
-//#endregion
-export { WEBHOOK_HEADERS as a, WEBHOOK_EVENT_TYPE_HEADER as i, WEBHOOK_DELIVERY_ID_HEADER as n, WEBHOOK_SIGNATURE_HEADER as o, WEBHOOK_EVENT_ID_HEADER as r, WEBHOOK_USER_AGENT as s, WEBHOOK_DEFAULT_TOLERANCE_SEC as t };