@sayren/store-sdk 0.29.6 → 0.29.8

package/package.json

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

package/src/client.ts

@@ -69,6 +69,28 @@ import {
   collectionProductsReplaceRequestSchema,
   collectionSchema,
 } from "./schemas/collection";
+import {
+  type CreateCommerceFlowRequest,
+  commerceFlowCheckSchema,
+  commerceFlowSchema,
+  commerceFlowSummarySchema,
+  createCommerceFlowRequestSchema,
+  flowActionRequestSchema,
+  flowActionResultSchema,
+  flowAssignmentRuleSchema,
+  flowPresetSummarySchema,
+  flowSecretSchema,
+  orderItemFlowSchema,
+  resolvedFlowSchema,
+  type SaveFlowAssignmentRulesRequest,
+  type SaveFlowDraftRequest,
+  type SaveFlowSecretRequest,
+  saveFlowAssignmentRulesRequestSchema,
+  saveFlowDraftRequestSchema,
+  saveFlowSecretRequestSchema,
+  type TestFlowAssignmentRequest,
+  testFlowAssignmentRequestSchema,
+} from "./schemas/commerce-flow";
 import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
 import {
   type CreateCouponRequest,
@@ -95,6 +117,11 @@ import {
   type WithdrawCustomerRequest,
   withdrawCustomerRequestSchema,
 } from "./schemas/customer";
+import {
+  type PickupLocationRequestInput,
+  pickupLocationRequestSchema,
+  pickupLocationSchema,
+} from "./schemas/fulfillment";
 import {
   type LoginProvider,
   loginProviderTestSchema,
@@ -215,6 +242,12 @@ import {
   savedOptionSetRequestSchema,
   savedOptionSetSchema,
 } from "./schemas/saved-option-set";
+import {
+  calendarDaySchema,
+  calendarQuerySchema,
+  type SetCalendarRequest,
+  setCalendarRequestSchema,
+} from "./schemas/stay";
 import {
   type AddressType,
   type Invitation,
@@ -506,6 +539,24 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       removeDiscount: (productId: string) =>
         storeHttp.requestVoid("DELETE", path`/products/${productId}/discount`),
+      /** 날짜별 재고 상품(`inventoryMode: "DATED"`, 이슈 #118)의 기간(포함) 달력. 없는 날은 싣지 않는다 */
+      getCalendar: (productId: string, query: z.input<typeof calendarQuerySchema>) =>
+        storeHttp.request(
+          "GET",
+          path`/products/${productId}/calendar`,
+          z.array(calendarDaySchema),
+          {
+            query: calendarQuerySchema.parse(query) as Query,
+          },
+        ),
+      /** 기간의 날짜마다 조합별 재고·가격을 덮어쓴다. `price: null`은 조합 가격으로 되돌린다 */
+      setCalendar: (productId: string, body: SetCalendarRequest) =>
+        storeHttp.request(
+          "PUT",
+          path`/products/${productId}/calendar`,
+          z.object({ updated: z.number().int() }),
+          { body: setCalendarRequestSchema.parse(body) },
+        ),
     },
 
     /**
@@ -730,6 +781,106 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       getDelivery: (orderItemId: string) =>
         storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema),
+      /** `GET /order-items/{id}/flow` — 커머스 플로우의 지금 상태·할 수 있는 행동·타이머(#115). 스코프 `order:r` */
+      getFlow: (orderItemId: string) =>
+        storeHttp.request("GET", path`/order-items/${orderItemId}/flow`, orderItemFlowSchema),
+      /**
+       * `POST /order-items/{id}/actions/{key}` — `getFlow().actions`에 켜진 행동을 실행한다(#115). 묶음 진행이면
+       * `affectedOrderItemIds`에 함께 움직인 주문상품이 온다. 에러: 409 `ACTION_NOT_AVAILABLE`
+       */
+      act: (
+        orderItemId: string,
+        key: string,
+        input: Record<string, unknown> = {},
+        idempotencyKey?: string,
+      ) =>
+        storeHttp.request(
+          "POST",
+          path`/order-items/${orderItemId}/actions/${key}`,
+          flowActionResultSchema,
+          { body: flowActionRequestSchema.parse({ input }), headers: idempotency(idempotencyKey) },
+        ),
+      /**
+       * `POST /order-items/{id}/events/{key}` — 현장 단말·연동의 상점 사건(`custom.<이름>`)을 플로우에 넣는다(#115).
+       * 에러: 400 `FLOW_EVENT_KEY_INVALID`, 409 `FLOW_EVENT_NOT_ACCEPTED`
+       */
+      emitEvent: (
+        orderItemId: string,
+        key: `custom.${string}`,
+        input: Record<string, unknown> = {},
+        idempotencyKey?: string,
+      ) =>
+        storeHttp.request(
+          "POST",
+          path`/order-items/${orderItemId}/events/${key}`,
+          flowActionResultSchema,
+          { body: flowActionRequestSchema.parse({ input }), headers: idempotency(idempotencyKey) },
+        ),
+    },
+
+    /**
+     * 커머스 플로우 (이슈 #115) — 프리셋 설치·초안 저장·검사·게시와 상품 할당 규칙. 조회 `flow:r`, 쓰기 `flow:rw`.
+     * 게시한 버전은 불변이고, 진행 중 주문은 결제 때 붙은 버전으로 끝까지 간다.
+     */
+    commerceFlows: {
+      presets: () => storeHttp.request("GET", "/flow-presets", z.array(flowPresetSummarySchema)),
+      list: () => storeHttp.request("GET", "/commerce-flows", z.array(commerceFlowSummarySchema)),
+      get: (flowId: string) =>
+        storeHttp.request("GET", path`/commerce-flows/${flowId}`, commerceFlowSchema),
+      /** 프리셋 설치 또는 빈 플로우. 에러: 409 `FLOW_KEY_TAKEN`·`FLOW_PRESET_UNAVAILABLE` */
+      create: (body: CreateCommerceFlowRequest) =>
+        storeHttp.request("POST", "/commerce-flows", commerceFlowSchema, {
+          body: createCommerceFlowRequestSchema.parse(body),
+        }),
+      /** 초안 저장. `revision`을 주면 그 초안일 때만 저장한다(409 `FLOW_REVISION_CONFLICT`) */
+      saveDraft: (flowId: string, body: SaveFlowDraftRequest, revision?: number) =>
+        storeHttp.request("PUT", path`/commerce-flows/${flowId}/draft`, commerceFlowSchema, {
+          body: saveFlowDraftRequestSchema.parse(body),
+          headers: revision === undefined ? undefined : { "if-match": String(revision) },
+        }),
+      check: (flowId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/commerce-flows/${flowId}/draft/check`,
+          commerceFlowCheckSchema,
+        ),
+      /** 게시. 차단 오류가 있으면 409 `PUBLISH_BLOCKED`(`details.blocking`) */
+      publish: (flowId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/commerce-flows/${flowId}/draft/publish`,
+          commerceFlowSchema,
+        ),
+      rules: () =>
+        storeHttp.request(
+          "GET",
+          "/commerce-flows/assignment-rules",
+          z.array(flowAssignmentRuleSchema),
+        ),
+      /** 할당 규칙 전체 교체(우선순위는 배열 순서). 에러: 400 `FLOW_ASSIGNMENT_CONDITION_INVALID`, 409 `FLOW_NOT_PUBLISHED` */
+      saveRules: (body: SaveFlowAssignmentRulesRequest) =>
+        storeHttp.request(
+          "PUT",
+          "/commerce-flows/assignment-rules",
+          z.array(flowAssignmentRuleSchema),
+          { body: saveFlowAssignmentRulesRequestSchema.parse(body) },
+        ),
+      testRules: (body: TestFlowAssignmentRequest) =>
+        storeHttp.request("POST", "/commerce-flows/assignment-rules/test", resolvedFlowSchema, {
+          body: testFlowAssignmentRequestSchema.parse(body),
+        }),
+      /** 이 상품에 지금 붙을 플로우 */
+      forProduct: (productId: string) =>
+        storeHttp.request("GET", path`/products/${productId}/flow`, resolvedFlowSchema),
+      /** HTTP 노드 시크릿 목록(헤더 값 제외) */
+      secrets: () => storeHttp.request("GET", "/commerce-flows/secrets", z.array(flowSecretSchema)),
+      /** 시크릿 저장(같은 이름이면 덮어쓴다). 상점 플랫폼 OWNER·ADMIN만. 에러: 400 `FLOW_SECRET_URL_INVALID` */
+      saveSecret: (name: string, body: SaveFlowSecretRequest) =>
+        storeHttp.request("PUT", path`/commerce-flows/secrets/${name}`, flowSecretSchema, {
+          body: saveFlowSecretRequestSchema.parse(body),
+        }),
+      removeSecret: (name: string) =>
+        storeHttp.requestVoid("DELETE", path`/commerce-flows/secrets/${name}`),
     },
 
     carriers: {
@@ -1335,6 +1486,21 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("POST", path`/seller-addresses/${addressId}/default`),
     },
 
+    /** 픽업 장소 (이슈 #115) — 방문 수령 주문의 수령 장소. 조회 `store:r`, 쓰기 `store:rw`(상점 플랫폼 OWNER·ADMIN) */
+    pickupLocations: {
+      list: () => storeHttp.request("GET", "/pickup-locations", z.array(pickupLocationSchema)),
+      create: (body: PickupLocationRequestInput) =>
+        storeHttp.request("POST", "/pickup-locations", pickupLocationSchema, {
+          body: pickupLocationRequestSchema.parse(body),
+        }),
+      update: (locationId: string, body: PickupLocationRequestInput) =>
+        storeHttp.request("PUT", path`/pickup-locations/${locationId}`, pickupLocationSchema, {
+          body: pickupLocationRequestSchema.parse(body),
+        }),
+      remove: (locationId: string) =>
+        storeHttp.requestVoid("DELETE", path`/pickup-locations/${locationId}`),
+    },
+
     /**
      * 스토어프론트 호스팅 (이슈 #53) — 조회 `storefront:r`, 쓰기 `storefront:rw`(OWNER·ADMIN).
      * 쓰기 응답은 바뀐 사이트다. Cloudflare 반영은 커밋 뒤라 `provisioning.status`가 잠시 `PENDING`일 수 있다.

package/src/index.ts

@@ -23,6 +23,7 @@ export * from "./schemas/auth";
 export * from "./schemas/category";
 export * from "./schemas/claim";
 export * from "./schemas/collection";
+export * from "./schemas/commerce-flow";
 export * from "./schemas/commerce-number";
 export * from "./schemas/common";
 export * from "./schemas/coupon";
@@ -40,6 +41,7 @@ export * from "./schemas/refund-policy";
 export * from "./schemas/saved-option-set";
 export * from "./schemas/scope";
 export * from "./schemas/shipping-policy";
+export * from "./schemas/stay";
 export * from "./schemas/store";
 export * from "./schemas/storefront-hosting";
 export * from "./schemas/subscription";

package/src/schemas/commerce-flow.ts

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import { claimStatusSchema } from "./claim";
+import { orderItemStatusSchema } from "./common";
+
+/**
+ * 커머스 플로우(이슈 #115) — 주문상품이 따르는 플로우의 지금 상태와 할 수 있는 행동. 공개 계약은 필드 추가로만 자란다.
+ * 행동 키·필드 키·꺼진 이유는 상점·앱이 늘리는 **열린 문자열**이다(모르는 값도 파싱한다). 공개 상태(`coreStatus`)만 닫힌 8개 값이다.
+ * 화면은 이 값만 그리고 상태 이름으로 분기하지 않는다 — 판정은 서버가 한다.
+ */
+
+export const flowInputFieldSchema = z.object({
+  key: z.string(),
+  type: z.string().describe("text · number · select · date · datetime · image (늘어날 수 있다)"),
+  required: z.boolean(),
+  label: z.string(),
+  maxLength: z.number().int().optional(),
+  maxFiles: z.number().int().optional(),
+  options: z.array(z.union([z.string(), z.number()])).optional(),
+});
+export type FlowInputField = z.infer<typeof flowInputFieldSchema>;
+
+export const flowActionSchema = z.object({
+  key: z.string().describe("행동 키. 플랫폼 키(예: CONFIRM_ORDER)와 상점·앱이 정한 키가 섞인다"),
+  label: z.string().describe("보여 줄 이름"),
+  mode: z
+    .enum(["INSTANT", "REQUEST", "VIEW"])
+    .describe("INSTANT 바로 실행 · REQUEST 승인 요청(클레임) · VIEW 보기"),
+  enabled: z.boolean(),
+  disabled: z
+    .object({
+      reason: z.string().describe("EXPIRED · CONDITION (늘어날 수 있다)"),
+      message: z.string().optional(),
+    })
+    .optional()
+    .describe("꺼진 이유. 켜져 있으면 없다"),
+  availableUntil: z.string().optional().describe("이 시각까지만 할 수 있다(ISO 8601)"),
+  subflow: z.string().optional().describe("이 행동이 시작하는 하위 플로우(클레임)"),
+  input: z.array(flowInputFieldSchema).optional().describe("받는 입력 폼"),
+  partialQuantity: z.union([z.boolean(), z.literal("UNIT")]).optional(),
+});
+export type FlowAction = z.infer<typeof flowActionSchema>;
+
+/** 커스텀 필드 값 — 문자열(날짜·일시는 ISO 8601)·숫자·참거짓·null, 수량 단위 필드는 문자열 배열 */
+export const flowFieldValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(z.string()),
+]);
+export type FlowFieldValue = z.infer<typeof flowFieldValueSchema>;
+
+export const flowStateSchema = z.object({
+  key: z.string().describe("플로우 안 상태 키(상점이 정한다). 화면 분기에 쓰지 않는다"),
+  label: z.string().describe("보는 사람(셀러·구매자)의 상태 이름"),
+  coreStatus: orderItemStatusSchema.optional().describe("공개 상태(8개)"),
+  claimStatus: claimStatusSchema.optional(),
+  message: z.string().optional().describe("보는 사람에게 보여 줄 안내문"),
+  enteredAt: z.string().describe("이 상태에 들어온 시각(ISO 8601)"),
+  deadlineAt: z.string().optional().describe("가장 가까운 기한(ISO 8601)"),
+  attachments: z
+    .array(z.string())
+    .optional()
+    .describe("가장 최근 행동이 붙인 첨부 주소(시안 등, #115). 없으면 생략"),
+  progress: z.boolean().optional().describe("진행 단계 표시에 넣는 상태인가"),
+  fields: z.record(z.string(), flowFieldValueSchema).describe("보는 사람 공개 범위의 커스텀 필드"),
+});
+export type FlowState = z.infer<typeof flowStateSchema>;
+
+export const orderItemFlowSchema = z.object({
+  orderItemId: z.string(),
+  flow: z.object({ flowId: z.string(), version: z.number().int() }),
+  flowState: flowStateSchema,
+  actions: z.array(flowActionSchema),
+  timers: z
+    .array(z.object({ key: z.string(), dueAt: z.string(), paused: z.boolean() }))
+    .describe("걸린 타이머(셀러 보기)"),
+  ended: z.boolean(),
+});
+export type OrderItemFlow = z.infer<typeof orderItemFlowSchema>;
+
+export const flowActionRequestSchema = z.object({
+  input: z.record(z.string(), z.unknown()).optional().describe("행동 입력 — 행동의 `input` 폼 키"),
+});
+export type FlowActionRequest = z.infer<typeof flowActionRequestSchema>;
+
+/**
+ * 행동 실행 결과. 지금은 동기 완료(COMPLETED)뿐이다. 외부 호출이 든 전이는 202와 함께 ACCEPTED(runId)가 온다(HTTP·앱 노드 단계에서 더한다).
+ * 동기 거절은 409(ACTION_NOT_AVAILABLE)다.
+ */
+export const flowActionResultSchema = z.object({
+  status: z.literal("COMPLETED"),
+  flowState: flowStateSchema,
+  actions: z.array(flowActionSchema),
+  /** 이 행동으로 바뀐 주문상품(주문 묶음 진행이면 여럿) */
+  affectedOrderItemIds: z.array(z.string()),
+});
+export type FlowActionResult = z.infer<typeof flowActionResultSchema>;
+
+// ── 플로우 정의 관리(이슈 #115 D3a) — `/v1/commerce-flows/**`, 스코프 `flow:r|rw` ─────────────────────
+
+/** 플로우 작성 그래프와 정의는 형태가 크고 노드 종류가 늘어나므로 여기서는 열린 객체로 싣는다(검증은 서버 `…/draft/check`) */
+const flowDocumentSchema = z.record(z.string(), z.unknown());
+
+export const flowPresetSummarySchema = z.object({
+  key: z.string(),
+  presetVersion: z.number().int(),
+  name: z.string(),
+  description: z.string(),
+  availability: z
+    .enum(["AVAILABLE", "BLOCKED"])
+    .describe("BLOCKED면 의존 이슈(dependsOn)가 끝나야 설치할 수 있다"),
+  dependsOn: z.array(z.string()),
+  requires: flowDocumentSchema.describe(
+    "프리셋이 쓰는 Core 기능(진행 단위·이행 방식·주문 입력 등)",
+  ),
+  variables: z.array(flowDocumentSchema).describe("셀러가 값만 입력하는 변수 정의"),
+});
+export type FlowPresetSummary = z.infer<typeof flowPresetSummarySchema>;
+
+export const commerceFlowSummarySchema = z.object({
+  flowId: z.string(),
+  key: z.string().describe("상점 안 유일한 키"),
+  name: z.string(),
+  progression: z.enum(["ITEM", "ORDER_GROUP"]),
+  fulfillmentMethods: z.array(z.string()),
+  presetKey: z.string().nullable().describe("설치한 프리셋(설치 뒤 연결되지 않는다)"),
+  presetVersion: z.number().int().nullable(),
+  activeVersion: z.number().int().nullable().describe("게시된 버전. 새 주문이 따른다"),
+  archivedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type CommerceFlowSummary = z.infer<typeof commerceFlowSummarySchema>;
+
+export const commerceFlowVersionViewSchema = z.object({
+  version: z.number().int(),
+  status: z.enum(["DRAFT", "ACTIVE", "LEGACY"]),
+  revision: z.number().int().describe("초안 저장의 If-Match 값"),
+  graph: flowDocumentSchema,
+  definition: flowDocumentSchema,
+  variables: z.record(z.string(), z.unknown()),
+  publishedAt: z.string().nullable(),
+});
+
+export const commerceFlowSchema = commerceFlowSummarySchema.extend({
+  draft: commerceFlowVersionViewSchema.nullable(),
+  active: commerceFlowVersionViewSchema.nullable(),
+  versions: z.array(
+    z.object({
+      version: z.number().int(),
+      status: z.enum(["DRAFT", "ACTIVE", "LEGACY"]),
+      publishedAt: z.string().nullable(),
+    }),
+  ),
+});
+export type CommerceFlow = z.infer<typeof commerceFlowSchema>;
+
+export const createCommerceFlowRequestSchema = z.object({
+  key: z
+    .string()
+    .regex(/^[a-z][a-z0-9-]{1,48}$/)
+    .describe("상점 안 유일한 키(소문자·숫자·하이픈)"),
+  name: z.string().min(1).max(60).optional(),
+  presetKey: z.string().optional().describe("설치할 프리셋. 없으면 빈 플로우"),
+  variables: z.record(z.string(), z.unknown()).optional().describe("프리셋 변수 값"),
+});
+export type CreateCommerceFlowRequest = z.infer<typeof createCommerceFlowRequestSchema>;
+
+export const saveFlowDraftRequestSchema = z.object({
+  graph: flowDocumentSchema,
+  definition: flowDocumentSchema.optional(),
+  variables: z.record(z.string(), z.unknown()).optional(),
+});
+export type SaveFlowDraftRequest = z.infer<typeof saveFlowDraftRequestSchema>;
+
+const flowIssueSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  nodeId: z.string().optional(),
+  edgeId: z.string().optional(),
+});
+
+export const commerceFlowCheckSchema = z.object({
+  publishable: z.boolean().describe("게시를 막는 오류(실행 불가·공개 계약·한도)가 없다"),
+  blocking: z.array(flowIssueSchema),
+  warnings: z.array(flowIssueSchema).describe("업무 논리 경고 — 게시를 막지 않는다"),
+});
+export type CommerceFlowCheck = z.infer<typeof commerceFlowCheckSchema>;
+
+// ── 할당 규칙(이슈 #115 D3b) — `/v1/commerce-flows/assignment-rules`, 스코프 `flow:r|rw` ─────────────────
+
+export const flowAssignmentRuleSchema = z.object({
+  ruleId: z.string(),
+  priority: z.number().int().describe("작을수록 먼저 본다"),
+  condition: z
+    .string()
+    .describe(
+      'CEL 조건식. 읽는 값: product(id·category·categoryPath·tags), order(amount·paymentMethod), buyer(member). 예: `"cat_1" in product.categoryPath`',
+    ),
+  flowId: z.string(),
+});
+export type FlowAssignmentRule = z.infer<typeof flowAssignmentRuleSchema>;
+
+export const saveFlowAssignmentRulesRequestSchema = z.object({
+  rules: z
+    .array(z.object({ condition: z.string().min(1).max(500), flowId: z.string() }))
+    .max(50)
+    .describe("위에서부터 처음 맞는 규칙의 게시된 플로우를 쓴다. 목록 전체를 바꾼다"),
+});
+export type SaveFlowAssignmentRulesRequest = z.infer<typeof saveFlowAssignmentRulesRequestSchema>;
+
+export const resolvedFlowSchema = z.object({
+  flowId: z.string(),
+  version: z.number().int(),
+  source: z
+    .enum(["RULE", "PLATFORM"])
+    .describe("RULE 할당 규칙 · PLATFORM 맞는 규칙이 없어 플랫폼 기본 플로우"),
+  ruleId: z.string().optional(),
+});
+export type ResolvedFlow = z.infer<typeof resolvedFlowSchema>;
+
+export const testFlowAssignmentRequestSchema = z.object({
+  productId: z.string(),
+  orderAmount: z.number().int().nonnegative().optional(),
+  paymentMethod: z.string().optional(),
+  member: z.boolean().optional(),
+});
+export type TestFlowAssignmentRequest = z.infer<typeof testFlowAssignmentRequestSchema>;
+
+// ─── 플로우 시크릿(이슈 #115 E5b) ─────────────────────────────
+
+/** 시크릿 이름 — 플로우 변수 `secretRef`의 값이다 */
+export const flowSecretNameSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]{1,39}$/)
+  .describe("시크릿 이름(소문자·숫자·하이픈 2~40자). 플로우 변수(시크릿)의 값으로 쓴다");
+
+/** HTTP 노드가 부를 셀러 API — 헤더 값은 응답에 싣지 않는다 */
+export const flowSecretSchema = z.object({
+  name: z.string(),
+  url: z.string().describe("요청 주소(https)"),
+  headerNames: z.array(z.string()).describe("저장한 헤더 이름(값은 보이지 않는다)"),
+  updatedAt: z.string(),
+});
+export type FlowSecret = z.infer<typeof flowSecretSchema>;
+
+export const saveFlowSecretRequestSchema = z.object({
+  url: z
+    .url()
+    .refine((value) => value.startsWith("https://"), { message: "https 주소만 받습니다" })
+    .describe("요청 주소. https만, 사설·루프백 주소는 400 `FLOW_SECRET_URL_INVALID`"),
+  headers: z
+    .record(z.string().regex(/^[A-Za-z0-9-]{1,64}$/), z.string().max(2000))
+    .refine((value) => Object.keys(value).length <= 10, { message: "헤더는 10개까지입니다" })
+    .default({})
+    .describe("함께 보낼 헤더(인증 등). 값은 암호화해 두고 다시 보여 주지 않는다"),
+});
+export type SaveFlowSecretRequest = z.input<typeof saveFlowSecretRequestSchema>;

package/src/schemas/coupon.ts

@@ -23,11 +23,15 @@ export const couponStatusSchema = z
   .describe("쿠폰 상태. `ACTIVE`=사용 중, `PAUSED`=중지(재개 가능), `ENDED`=종료(되돌릴 수 없음)");
 export type CouponStatus = z.infer<typeof couponStatusSchema>;
 
-/** 지금 만들 수 있는 발급 방식 — 다운로드·가입 자동 지급은 뒤 단계다 */
+/**
+ * 발급 방식 — 코드 입력·셀러 지급·다운로드(구매자가 받기)·회원가입 자동 지급(이슈 #110).
+ * 응답(`couponSchema.issueMethod`)은 값이 늘 수 있어 문자열로 받는다. 이 enum은 요청 검증용이다.
+ */
 export const couponIssueMethodSchema = z
-  .enum(["CODE", "MANUAL"])
+  .enum(["CODE", "MANUAL", "DOWNLOAD", "SIGNUP"])
   .describe(
-    "발급 방식. `CODE`=구매자가 주문서에 코드를 입력한다, `MANUAL`=셀러가 회원을 골라 지급한다",
+    "발급 방식. `CODE`=구매자가 주문서에 코드를 입력한다, `MANUAL`=셀러가 회원을 골라 지급한다, " +
+      "`DOWNLOAD`=구매자가 스토어프론트에서 받는다, `SIGNUP`=회원가입 때 자동으로 지급한다",
   );
 export type CouponIssueMethod = z.infer<typeof couponIssueMethodSchema>;
 
@@ -51,10 +55,12 @@ const descriptions = {
     "사용 종료 시각(ISO 8601, 시간대 포함). 이 시각부터 못 쓴다. 생략하면 제한이 없다. " +
     "이미 지급한 쿠폰의 유효 기간은 지급 때 정해지므로 뒤에 종료일을 늦춰도 늘어나지 않는다",
   validDaysAfterIssue:
-    "발급 후 유효 일수 — 셀러 지급(`MANUAL`) 쿠폰만. 쿠폰 종료일과 둘 중 먼저 끝나는 쪽이 적용된다",
-  totalIssueLimit: "총 발급 수 한도. 생략하면 무제한",
+    "발급 후 유효 일수 — 발급형(`MANUAL`·`DOWNLOAD`·`SIGNUP`) 쿠폰만. 쿠폰 종료일과 둘 중 먼저 끝나는 쪽이 적용된다",
+  totalIssueLimit:
+    "총 발급 수 한도. 생략하면 무제한. 다운로드·회원가입 쿠폰은 한도에 닿으면 더 발급하지 않는다",
   totalUseLimit: "총 사용 수 한도. 결제 중인 예약도 센다. 생략하면 무제한",
-  perMemberIssueLimit: "1인 발급 수 한도(셀러 지급). 생략하면 1인 1장",
+  perMemberIssueLimit:
+    "1인 발급 수 한도(셀러 지급·다운로드). 생략하면 1인 1장. 회원가입 쿠폰은 1장 고정이라 1만 받는다",
   perMemberUseLimit:
     "1인 사용 수 한도(코드 입력형). 생략하면 무제한. 비회원에게 여는 쿠폰은 둘 수 없다",
 } as const;
@@ -117,12 +123,19 @@ export const createCouponRequestSchema = z
       issue("validDaysAfterIssue", "발급 후 유효 일수는 셀러 지급 쿠폰에만 둡니다");
     }
     if (body.issueMethod === "CODE" && body.perMemberIssueLimit != null) {
-      issue("perMemberIssueLimit", "1인 발급 수 한도는 셀러 지급 쿠폰에만 둡니다");
+      issue("perMemberIssueLimit", "1인 발급 수 한도는 발급형 쿠폰에만 둡니다");
+    }
+    if (
+      body.issueMethod === "SIGNUP" &&
+      body.perMemberIssueLimit != null &&
+      body.perMemberIssueLimit !== 1
+    ) {
+      issue("perMemberIssueLimit", "회원가입 쿠폰은 1인 1장입니다");
     }
-    if (body.issueMethod === "MANUAL" && body.perMemberUseLimit != null) {
+    if (body.issueMethod !== "CODE" && body.perMemberUseLimit != null) {
       issue(
         "perMemberUseLimit",
-        "셀러 지급 쿠폰은 발급 한 장이 한 번 쓰입니다. 1인 발급 수 한도를 쓰십시오",
+        "발급형 쿠폰은 발급 한 장이 한 번 쓰입니다. 1인 발급 수 한도를 사용하십시오",
       );
     }
     const memberOnly = body.conditions?.memberOnly ?? COUPON_CONDITIONS_DEFAULTS.memberOnly;
@@ -168,7 +181,7 @@ export const couponSchema = z.object({
   issueMethod: z
     .string()
     .describe(
-      "발급 방식. 현재 값은 `CODE`·`MANUAL`이고 값이 추가될 수 있어 문자열로 받는다(다운로드·가입 자동 지급 예정)",
+      "발급 방식. 현재 값은 `CODE`·`MANUAL`·`DOWNLOAD`(구매자가 받기)·`SIGNUP`(회원가입 자동 지급)이고 값이 추가될 수 있어 문자열로 받는다",
     ),
   code: z.string().nullable().describe("쿠폰 코드(대문자). 코드 입력형이 아니면 null"),
   startsAt: z.string().nullable(),
@@ -214,6 +227,12 @@ export const couponIssueSchema = z.object({
   couponId: z.string(),
   customerId: z.string(),
   customerName: z.string().nullable().describe("구매자 이름. 탈퇴한 구매자는 null"),
+  source: z
+    .string()
+    .optional()
+    .describe(
+      "발급 경로(이슈 #110). 현재 값은 `MANUAL`(셀러 지급)·`DOWNLOAD`(구매자가 받음)·`SIGNUP`(회원가입 자동 지급)이고 값이 추가될 수 있다. 서버는 항상 싣는다",
+    ),
   status: couponIssueStatusSchema,
   validFrom: z.string(),
   validUntil: z.string().nullable(),