@sayren/store-sdk 0.50.0 → 0.51.0

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { a as WEBHOOK_HEADERS, i as WEBHOOK_EVENT_TYPE_HEADER, n as WEBHOOK_DELIVERY_ID_HEADER, o as WEBHOOK_SIGNATURE_HEADER, r as WEBHOOK_EVENT_ID_HEADER, s as WEBHOOK_USER_AGENT, t as WEBHOOK_DEFAULT_TOLERANCE_SEC } from "./webhook-headers-D6QmPdEJ.mjs";
+import { c as WEBHOOK_DELIVERY_ID_HEADER, d as WEBHOOK_HEADERS, f as WEBHOOK_SIGNATURE_HEADER, l as WEBHOOK_EVENT_ID_HEADER, p as WEBHOOK_USER_AGENT, r as CustomerUserinfoInput, s as WEBHOOK_DEFAULT_TOLERANCE_SEC, u as WEBHOOK_EVENT_TYPE_HEADER } from "./userinfo-n1JYxWAz.mjs";
 //#region src/member-delegation.d.ts
 /**
  * 구매자 위임 — 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰으로 바꾼다.
@@ -31,6 +31,8 @@ export declare function delegateMember(options: {
   email?: string;
   name?: string;
   authenticatedAt?: Date;
+  /** OIDC 클레임(이슈 #264) — 준 클레임만 바뀌고 null은 지운다 */
+  userinfo?: CustomerUserinfoInput;
   fetch?: typeof globalThis.fetch;
 }): Promise<DelegatedMemberToken>;
 //#endregion

package/dist/server.mjs

@@ -29,7 +29,8 @@ async function delegateMember(options) {
 			...options.uid ? { uid: options.uid } : {},
 			...options.email ? { email: options.email } : {},
 			...options.name ? { name: options.name } : {},
-			...options.authenticatedAt ? { authenticatedAt: options.authenticatedAt.toISOString() } : {}
+			...options.authenticatedAt ? { authenticatedAt: options.authenticatedAt.toISOString() } : {},
+			...options.userinfo ? { userinfo: options.userinfo } : {}
 		})
 	});
 	const body = await res.json().catch(() => ({}));

package/dist/userinfo-n1JYxWAz.d.mts

@@ -0,0 +1,90 @@
+import * as z$1 from "zod";
+//#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
+//#region src/schemas/userinfo.d.ts
+/**
+ * 구매자 정보의 OIDC userinfo 표준 클레임(OpenID Connect Core 1.0 5.1, 이슈 #264). 이름은 표준 그대로 snake_case다.
+ * 값이 없는 클레임은 응답에서 빠진다. 같은 형식이 스토어프론트 API(storefront-sdk `userinfoSchema`)에도 있다.
+ */
+/** 생일 — `YYYY-MM-DD`, 연도를 모르면 `0000-MM-DD`(표준 형식) */
+declare const CUSTOMER_BIRTHDATE_PATTERN: RegExp;
+declare const customerUserinfoAddressSchema: z$1.ZodObject<{
+  formatted: z$1.ZodOptional<z$1.ZodString>;
+  street_address: z$1.ZodOptional<z$1.ZodString>;
+  locality: z$1.ZodOptional<z$1.ZodString>;
+  region: z$1.ZodOptional<z$1.ZodString>;
+  postal_code: z$1.ZodOptional<z$1.ZodString>;
+  country: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>;
+declare const customerUserinfoSchema: z$1.ZodObject<{
+  sub: z$1.ZodString;
+  name: z$1.ZodOptional<z$1.ZodString>;
+  given_name: z$1.ZodOptional<z$1.ZodString>;
+  family_name: z$1.ZodOptional<z$1.ZodString>;
+  middle_name: z$1.ZodOptional<z$1.ZodString>;
+  nickname: z$1.ZodOptional<z$1.ZodString>;
+  preferred_username: z$1.ZodOptional<z$1.ZodString>;
+  profile: z$1.ZodOptional<z$1.ZodString>;
+  picture: z$1.ZodOptional<z$1.ZodString>;
+  website: z$1.ZodOptional<z$1.ZodString>;
+  email: z$1.ZodOptional<z$1.ZodString>;
+  email_verified: z$1.ZodOptional<z$1.ZodBoolean>;
+  gender: z$1.ZodOptional<z$1.ZodString>;
+  birthdate: z$1.ZodOptional<z$1.ZodString>;
+  zoneinfo: z$1.ZodOptional<z$1.ZodString>;
+  locale: z$1.ZodOptional<z$1.ZodString>;
+  phone_number: z$1.ZodOptional<z$1.ZodString>;
+  phone_number_verified: z$1.ZodOptional<z$1.ZodBoolean>;
+  address: z$1.ZodOptional<z$1.ZodObject<{
+    formatted: z$1.ZodOptional<z$1.ZodString>;
+    street_address: z$1.ZodOptional<z$1.ZodString>;
+    locality: z$1.ZodOptional<z$1.ZodString>;
+    region: z$1.ZodOptional<z$1.ZodString>;
+    postal_code: z$1.ZodOptional<z$1.ZodString>;
+    country: z$1.ZodOptional<z$1.ZodString>;
+  }, z$1.core.$strip>>;
+  updated_at: z$1.ZodOptional<z$1.ZodNumber>;
+}, z$1.core.$strip>;
+type CustomerUserinfo = z$1.infer<typeof customerUserinfoSchema>;
+/**
+ * 셀러가 위임으로 바꿀 수 있는 클레임 — 준 클레임만 바뀌고 null은 지운다. `sub`·`email`·`phone_number`·`updated_at`·`address`는 받지 않는다. 확인 여부(`*_verified`)는 셀러가 확인한 값을 받는다
+ * (이메일·휴대폰은 각자의 칸, 주소는 배송지가 원천이다)
+ */
+declare const customerUserinfoInputSchema: z$1.ZodObject<{
+  email_verified: z$1.ZodOptional<z$1.ZodBoolean>;
+  phone_number_verified: z$1.ZodOptional<z$1.ZodBoolean>;
+  given_name: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+  family_name: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+  middle_name: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+  nickname: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+  preferred_username: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+  profile: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodURL>>;
+  picture: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodURL>>;
+  website: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodURL>>;
+  gender: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+  birthdate: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+  zoneinfo: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+  locale: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
+}, z$1.core.$strict>;
+type CustomerUserinfoInput = z$1.infer<typeof customerUserinfoInputSchema>;
+//#endregion
+export { customerUserinfoInputSchema as a, WEBHOOK_DELIVERY_ID_HEADER as c, WEBHOOK_HEADERS as d, WEBHOOK_SIGNATURE_HEADER as f, customerUserinfoAddressSchema as i, WEBHOOK_EVENT_ID_HEADER as l, CustomerUserinfo as n, customerUserinfoSchema as o, WEBHOOK_USER_AGENT as p, CustomerUserinfoInput as r, WEBHOOK_DEFAULT_TOLERANCE_SEC as s, CUSTOMER_BIRTHDATE_PATTERN as t, WEBHOOK_EVENT_TYPE_HEADER as u };

package/package.json

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

package/src/client.ts

@@ -168,11 +168,13 @@ import {
 import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
 import {
   type CreateCouponRequest,
+  couponDistributionSchema,
   couponIssueSchema,
   type couponListQuerySchema,
   couponRedemptionSchema,
   couponSchema,
   couponStatsSchema,
+  couponVoucherCodesSchema,
   createCouponRequestSchema,
   customerCouponSchema,
   type IssueCouponRequest,
@@ -1550,6 +1552,33 @@ export function createStoreClient(options: StoreClientOptions) {
           body: issueCouponRequestSchema.parse(body),
           headers: idempotency(idempotencyKey),
         }),
+      /** 쿠폰 번호 전체(`VOUCHER`, #264) — 순번 순 */
+      voucherCodes: (couponId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/coupons/${couponId}/voucher-codes`,
+          couponVoucherCodesSchema,
+        ),
+      /** 발급 대상 전원 지급(#264) — 202로 작업을 만든다. 진행은 `distributions`·`distribution`으로 본다 */
+      distribute: (couponId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/coupons/${couponId}/distributions`,
+          couponDistributionSchema,
+        ),
+      /** 전원 지급 작업 목록(최근 20건, 최신순) */
+      distributions: (couponId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/coupons/${couponId}/distributions`,
+          z.array(couponDistributionSchema),
+        ),
+      distribution: (couponId: string, distributionId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/coupons/${couponId}/distributions/${distributionId}`,
+          couponDistributionSchema,
+        ),
       issues: (
         couponId: string,
         params?: PageParams & { status?: "AVAILABLE" | "RESERVED" | "USED" | "REVOKED" },

package/src/index.ts

@@ -67,6 +67,7 @@ export * from "./schemas/storefront-hosting";
 export * from "./schemas/subscription";
 export * from "./schemas/telemetry";
 export * from "./schemas/upload";
+export * from "./schemas/userinfo";
 export * from "./schemas/webhook-event";
 export {
   type AuthorizeOptions,

package/src/member-delegation.ts

@@ -1,4 +1,5 @@
 import { SAYREN_API_ORIGIN } from "./http";
+import type { CustomerUserinfoInput } from "./schemas/userinfo";
 /**
  * 구매자 위임 — 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰으로 바꾼다.
  * 계정 토큰(개인 액세스 토큰 등)을 쓰므로 **서버에서만** 부른다.
@@ -37,6 +38,8 @@ export async function delegateMember(options: {
   email?: string;
   name?: string;
   authenticatedAt?: Date;
+  /** OIDC 클레임(이슈 #264) — 준 클레임만 바뀌고 null은 지운다 */
+  userinfo?: CustomerUserinfoInput;
   fetch?: typeof globalThis.fetch;
 }): Promise<DelegatedMemberToken> {
   const doFetch = options.fetch ?? globalThis.fetch;
@@ -56,6 +59,7 @@ export async function delegateMember(options: {
         ...(options.authenticatedAt
           ? { authenticatedAt: options.authenticatedAt.toISOString() }
           : {}),
+        ...(options.userinfo ? { userinfo: options.userinfo } : {}),
       }),
     },
   );

package/src/schemas/condition-tree.ts

@@ -38,10 +38,60 @@ export function isConditionGroup(node: ConditionNode): node is ConditionGroup {
  * - `idSet`: 문자열 id(`in` — 값 목록 중 하나. 사실 값이 목록이면 하나라도 겹치면 참)
  * - `enumSet`: 정해진 선택지(`in`)
  * - `timeRange`: `HH:MM` 구간(`between` — `[시작, 끝]`, 끝 제외. 시작이 끝보다 크면 자정을 넘는 구간)
+ * - `birthdate`: 생일에서 나온 값(`BirthdateFact`). 만 나이 `ageBetween`(`[이상, 이하]`)·`age>=`·`age<=`, 생일 달 `birthMonthIn`(월 목록 1~12)·
+ *   `birthMonthIsCurrent`(값 `true` — 판정 시각이 생일 달). 연도를 모르는 생일은 나이 연산자가 거짓이다
  */
-export type ConditionValueType = "integer" | "boolean" | "idSet" | "enumSet" | "timeRange";
+export type ConditionValueType =
+  | "integer"
+  | "boolean"
+  | "idSet"
+  | "enumSet"
+  | "timeRange"
+  | "birthdate";
+
+export type ConditionOperator =
+  | "="
+  | ">="
+  | "<="
+  | "between"
+  | "in"
+  | "ageBetween"
+  | "age>="
+  | "age<="
+  | "birthMonthIn"
+  | "birthMonthIsCurrent";
+
+/** `birthdate` 사실 값 — 원본 날짜가 아니라 판정에 필요한 값만 둔다 */
+export interface BirthdateFact {
+  /** 만 나이. 연도를 모르면 생략 */
+  age?: number;
+  /** 생일 달(1~12) */
+  month: number;
+  /** 판정 시각이 생일 달인가 */
+  isCurrentMonth: boolean;
+}
+
+const BIRTHDATE_TEXT = /^(\d{4})-(\d{2})-(\d{2})$/;
 
-export type ConditionOperator = "=" | ">=" | "<=" | "between" | "in";
+/**
+ * 생일(`YYYY-MM-DD`, 연도를 모르면 `0000-MM-DD`)과 판정 날짜(쓰는 쪽 달력의 연·월·일)로 사실 값을 만든다. 읽지 못하면 undefined
+ */
+export function birthdateFactOf(
+  birthdate: string | null | undefined,
+  today: { year: number; month: number; day: number },
+): BirthdateFact | undefined {
+  const match = birthdate ? BIRTHDATE_TEXT.exec(birthdate) : null;
+  if (!match) return undefined;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  if (month < 1 || month > 12 || day < 1 || day > 31) return undefined;
+  const fact: BirthdateFact = { month, isCurrentMonth: month === today.month };
+  if (year > 0) {
+    const beforeBirthday = today.month < month || (today.month === month && today.day < day);
+    const age = today.year - year - (beforeBirthday ? 1 : 0);
+    if (age >= 0) fact.age = age;
+  }
+  return fact;
+}
 
 export const CONDITION_OPERATORS_BY_TYPE: Readonly<
   Record<ConditionValueType, readonly ConditionOperator[]>
@@ -51,8 +101,12 @@ export const CONDITION_OPERATORS_BY_TYPE: Readonly<
   idSet: ["in"],
   enumSet: ["in"],
   timeRange: ["between"],
+  birthdate: ["ageBetween", "age>=", "age<=", "birthMonthIn", "birthMonthIsCurrent"],
 };
 
+/** 나이 값 범위 */
+const AGE_MAX = 150;
+
 /** 필드 정의 — `Ctx`는 쓰는 쪽의 평가 컨텍스트다 */
 export interface ConditionFieldDef<Ctx> {
   name: string;
@@ -183,6 +237,26 @@ function valueValid<Ctx>(
         value.every((v) => typeof v === "string" && TIME_PATTERN.test(v)) &&
         value[0] !== value[1]
       );
+    case "birthdate": {
+      const age = { min: 0, max: AGE_MAX };
+      if (operator === "ageBetween")
+        return (
+          Array.isArray(value) &&
+          value.length === 2 &&
+          isInteger(value[0], age) &&
+          isInteger(value[1], age) &&
+          value[0] <= value[1]
+        );
+      if (operator === "age>=" || operator === "age<=") return isInteger(value, age);
+      if (operator === "birthMonthIn")
+        return (
+          Array.isArray(value) &&
+          value.length > 0 &&
+          value.length <= 12 &&
+          value.every((v) => isInteger(v, { min: 1, max: 12 }))
+        );
+      return operator === "birthMonthIsCurrent" && value === true;
+    }
   }
 }
 
@@ -250,7 +324,9 @@ export function canonicalizeConditionRule(rule: ConditionRule): ConditionRule {
   const value =
     rule.operator === "in" && Array.isArray(rule.value)
       ? [...new Set(rule.value as string[])].sort()
-      : rule.value;
+      : rule.operator === "birthMonthIn" && Array.isArray(rule.value)
+        ? [...new Set(rule.value as number[])].sort((a, b) => a - b)
+        : rule.value;
   return { field: rule.field, operator: rule.operator, value };
 }
 
@@ -311,6 +387,30 @@ function ruleHolds<Ctx>(rule: ConditionRule, catalog: ConditionCatalog<Ctx>, ctx
       // 끝 제외. 시작 > 끝이면 자정을 넘는 구간(22:00~02:00)
       return from < to ? at >= from && at < to : at >= from || at < to;
     }
+    case "birthdate": {
+      if (typeof fact !== "object") return false;
+      const birth = fact as BirthdateFact;
+      const age = birth.age;
+      if (operator === "ageBetween" && Array.isArray(value)) {
+        const [from, to] = value as [unknown, unknown];
+        return (
+          typeof age === "number" &&
+          typeof from === "number" &&
+          typeof to === "number" &&
+          age >= from &&
+          age <= to
+        );
+      }
+      if (operator === "age>=")
+        return typeof age === "number" && typeof value === "number" && age >= value;
+      if (operator === "age<=")
+        return typeof age === "number" && typeof value === "number" && age <= value;
+      if (operator === "birthMonthIn")
+        return Array.isArray(value) && (value as unknown[]).includes(birth.month);
+      if (operator === "birthMonthIsCurrent")
+        return value === true && birth.isCurrentMonth === true;
+      return false;
+    }
   }
 }
 

package/src/schemas/coupon-rules.ts

@@ -1,6 +1,8 @@
 import * as z from "zod";
 import {
   anyConditionHolds,
+  type BirthdateFact,
+  birthdateFactOf,
   type ConditionCatalog,
   type ConditionFieldDef,
   type ConditionGroup,
@@ -53,6 +55,62 @@ export interface CouponCustomerFacts {
   paidOrderCount?: number;
   /** 마지막 주문 뒤 지난 날 수(내림). 주문이 없으면 생략 */
   daysSinceLastOrder?: number;
+  /**
+   * 구매자 OIDC 클레임(이슈 #264)에서 나온 값 — `claims.*` 규칙이 읽는다. 주문 스냅샷에는 굳히지 않는다(`pickCouponFacts`) —
+   * 생일·성별을 주문에 남기지 않고, 클레임은 주문서 금액과 무관해 환불 재판정이 결제 시작의 판정을 그대로 따른다
+   */
+  claims?: CouponClaimFacts;
+}
+
+/** `claims.*` 사실 값 — 없는 클레임은 생략(그 규칙은 거짓) */
+export interface CouponClaimFacts {
+  gender?: string;
+  /** 생일에서 나온 나이·생일 달 — 원본 날짜는 두지 않는다 */
+  birthdate?: BirthdateFact;
+  email_verified?: boolean;
+  phone_number_verified?: boolean;
+  /** 언어 태그와 그 앞부분(`en-US` → `["en-US", "en"]`) */
+  locale?: string[];
+  /** 기본 배송지 국가(ISO 3166-1 alpha-2) */
+  addressCountry?: string;
+}
+
+/** BCP 47 정규형(`ko-kr` → `ko-KR`) — 사실 값과 규칙 값이 같은 표기여야 목록 비교가 맞는다. 읽지 못하면 undefined */
+export function canonicalLocale(tag: string | null | undefined): string | undefined {
+  if (!tag) return undefined;
+  try {
+    return Intl.getCanonicalLocales(tag)[0];
+  } catch {
+    return undefined;
+  }
+}
+
+/** 클레임 원본 → 사실 값. `now`는 판정 시각(생일 달·만 나이는 한국 날짜) */
+export function couponClaimFactsOf(
+  claims: {
+    gender?: string | null;
+    birthdate?: string | null;
+    email_verified?: boolean | null;
+    phone_number_verified?: boolean | null;
+    locale?: string | null;
+    addressCountry?: string | null;
+  },
+  now: Date,
+): CouponClaimFacts {
+  const facts: CouponClaimFacts = {};
+  if (claims.gender) facts.gender = claims.gender;
+  const birth = birthdateFactOf(claims.birthdate, couponTodayAt(now));
+  if (birth) facts.birthdate = birth;
+  if (typeof claims.email_verified === "boolean") facts.email_verified = claims.email_verified;
+  if (typeof claims.phone_number_verified === "boolean")
+    facts.phone_number_verified = claims.phone_number_verified;
+  const locale = canonicalLocale(claims.locale);
+  if (locale) {
+    const primary = locale.split("-")[0] ?? locale;
+    facts.locale = [...new Set([locale, primary])];
+  }
+  if (claims.addressCountry) facts.addressCountry = claims.addressCountry.toUpperCase();
+  return facts;
 }
 
 export interface CouponTimeFacts {
@@ -95,6 +153,19 @@ const WEEKDAY_OF: Record<string, CouponWeekday> = {
   Sun: "SUN",
 };
 
+const SEOUL_DATE = new Intl.DateTimeFormat("en-CA", {
+  timeZone: COUPON_TIME_ZONE,
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+});
+
+/** 판정 시각의 한국 날짜 */
+export function couponTodayAt(now: Date): { year: number; month: number; day: number } {
+  const parts = Object.fromEntries(SEOUL_DATE.formatToParts(now).map((p) => [p.type, p.value]));
+  return { year: Number(parts.year), month: Number(parts.month), day: Number(parts.day) };
+}
+
 /** 판정 시각의 요일·시각(Asia/Seoul) */
 export function couponTimeFactsAt(now: Date): CouponTimeFacts {
   const parts = Object.fromEntries(SEOUL.formatToParts(now).map((p) => [p.type, p.value]));
@@ -209,6 +280,43 @@ const ORDER_FIELDS: readonly (ConditionFieldDef<CouponOrderContext> &
     max: DAY_MAX,
     resolve: (ctx) => ctx.facts.customer?.daysSinceLastOrder,
   },
+  {
+    name: "claims.gender",
+    type: "enumSet",
+    slots: ["audience", "eligibility"],
+    options: ["female", "male"],
+    resolve: (ctx) => ctx.facts.customer?.claims?.gender,
+  },
+  {
+    name: "claims.birthdate",
+    type: "birthdate",
+    slots: ["audience", "eligibility"],
+    resolve: (ctx) => ctx.facts.customer?.claims?.birthdate,
+  },
+  {
+    name: "claims.email_verified",
+    type: "boolean",
+    slots: ["audience", "eligibility"],
+    resolve: (ctx) => ctx.facts.customer?.claims?.email_verified,
+  },
+  {
+    name: "claims.phone_number_verified",
+    type: "boolean",
+    slots: ["audience", "eligibility"],
+    resolve: (ctx) => ctx.facts.customer?.claims?.phone_number_verified,
+  },
+  {
+    name: "claims.locale",
+    type: "idSet",
+    slots: ["audience", "eligibility"],
+    resolve: (ctx) => ctx.facts.customer?.claims?.locale,
+  },
+  {
+    name: "claims.address.country",
+    type: "idSet",
+    slots: ["audience", "eligibility"],
+    resolve: (ctx) => ctx.facts.customer?.claims?.addressCountry,
+  },
   {
     name: "cart.subtotal",
     type: "integer",
@@ -547,6 +655,7 @@ export function assumeCouponFactRules(group: ConditionGroup, facts: CouponFacts)
       return (
         facts.customer?.[field.slice("customer.".length) as keyof CouponCustomerFacts] !== undefined
       );
+    if (field.startsWith("claims.")) return facts.customer?.claims !== undefined;
     if (field.startsWith("time.")) return facts.time !== undefined;
     return true;
   };
@@ -588,6 +697,8 @@ export function couponCustomerFactNames(
     for (const field of conditionFields(group)) {
       if (field.startsWith("customer."))
         names.add(field.slice("customer.".length) as keyof CouponCustomerFacts);
+      // 클레임은 한 묶음으로 읽는다(회원 행 + 기본 배송지)
+      if (field.startsWith("claims.")) names.add("claims");
     }
   }
   return names;
@@ -598,6 +709,8 @@ export function pickCouponFacts(facts: CouponFacts, eligibility: ConditionGroup)
   const fields = conditionFields(eligibility);
   const customer: CouponCustomerFacts = {};
   for (const name of couponCustomerFactNames(eligibility)) {
+    // 클레임은 굳히지 않는다 — 환불 재판정은 없는 사실을 통과로 본다(`assumeCouponFactRules`)
+    if (name === "claims") continue;
     const value = facts.customer?.[name];
     if (value !== undefined) (customer as Record<string, unknown>)[name] = value;
   }
@@ -702,6 +815,38 @@ export function couponRuleIssues(input: {
       path: ["perMemberUseLimit"],
       message: "결제 완료 주문 수 조건이 있는 코드 입력형 쿠폰은 1인 사용 한도가 필요합니다",
     });
+  // 클레임 목록 값은 사실 값과 같은 표기만 받는다 — 국가는 대문자 두 자, 언어 태그는 BCP 47 정규형(`ko-KR`, 앞부분은 `ko`)
+  for (const slot of ["eligibility", "audience"] as const) {
+    const walk = (group: ConditionGroup, path: (string | number)[]): void => {
+      for (const [index, node] of group.rules.entries()) {
+        const at = [...path, "rules", index];
+        if (isConditionGroup(node)) {
+          walk(node, at);
+          continue;
+        }
+        if (!Array.isArray(node.value)) continue;
+        const values = node.value as unknown[];
+        if (
+          node.field === "claims.address.country" &&
+          !values.every((v) => typeof v === "string" && /^[A-Z]{2}$/.test(v))
+        )
+          issues.push({
+            path: [...at, "value"],
+            message: "국가는 대문자 두 자 코드(예: KR)입니다",
+          });
+        if (
+          node.field === "claims.locale" &&
+          !values.every((v) => typeof v === "string" && canonicalLocale(v) === v)
+        )
+          issues.push({
+            path: [...at, "value"],
+            message: "언어 태그는 정규 표기(예: ko, ko-KR)입니다",
+          });
+      }
+    };
+    const group = input[slot];
+    if (group) walk(group, [slot]);
+  }
   if (
     input.issueMethod === "SIGNUP" &&
     couponCustomerFactNames(input.audience ?? EMPTY_CONDITION_GROUP).has("daysSinceJoined")
@@ -751,6 +896,8 @@ const FIELD_LABELS: Record<string, string> = {
   "line.unitPrice": "판매가",
 };
 
+const GENDER_LABELS: Record<string, string> = { female: "여성", male: "남성" };
+
 const number = new Intl.NumberFormat("ko-KR");
 
 function amountText(field: string, value: unknown, formatMoney: (minor: number) => string) {
@@ -785,6 +932,18 @@ export function describeCouponRule(
       const [from, to] = rule.value as [string, string];
       return `${from}~${to}`;
     }
+    case "claims.gender":
+      return (rule.value as string[]).map((g) => GENDER_LABELS[g] ?? g).join("·");
+    case "claims.email_verified":
+      return rule.value ? "이메일 확인 회원" : "이메일 미확인 회원";
+    case "claims.phone_number_verified":
+      return rule.value ? "휴대폰 확인 회원" : "휴대폰 미확인 회원";
+    case "claims.locale":
+      return `언어 ${(rule.value as string[]).join("·")}`;
+    case "claims.address.country":
+      return `국가 ${(rule.value as string[]).join("·")}`;
+    case "claims.birthdate":
+      return describeBirthdateRule(rule);
   }
   const text = (v: unknown) => amountText(rule.field, v, formatMoney);
   if (rule.operator === "between") {
@@ -797,6 +956,25 @@ export function describeCouponRule(
   return `${label} ${text(rule.value)}${suffix}`;
 }
 
+function describeBirthdateRule(rule: ConditionRule): string {
+  switch (rule.operator) {
+    case "ageBetween": {
+      const [from, to] = rule.value as [number, number];
+      return `만 ${from}~${to}세`;
+    }
+    case "age>=":
+      return `만 ${rule.value}세 이상`;
+    case "age<=":
+      return `만 ${rule.value}세 이하`;
+    case "birthMonthIn":
+      return `생일 ${(rule.value as number[]).join("·")}월`;
+    case "birthMonthIsCurrent":
+      return "생일 달";
+    default:
+      return "생일";
+  }
+}
+
 export function describeCouponGroup(
   group: ConditionGroup,
   formatMoney?: (minor: number) => string,