@sayren/store-sdk 0.30.0 → 0.30.2

package/src/schemas/commerce-flow.ts

@@ -10,9 +10,14 @@ import { orderItemStatusSchema } from "./common";
 
 export const flowInputFieldSchema = z.object({
   key: z.string(),
-  type: z.string().describe("text · number · select · date · datetime · image (늘어날 수 있다)"),
+  type: z
+    .string()
+    .describe(
+      "text · textarea · number · select · radio · checkbox · boolean · date · datetime · image (늘어날 수 있다). 값: checkbox는 고른 선택지 배열, boolean은 참거짓(필수면 true), date는 `YYYY-MM-DD`, datetime은 오프셋 있는 ISO 8601, image는 https 주소 배열",
+    ),
   required: z.boolean(),
   label: z.string(),
+  placeholder: z.string().optional().describe("입력 안내"),
   maxLength: z.number().int().optional(),
   maxFiles: z.number().int().optional(),
   options: z.array(z.union([z.string(), z.number()])).optional(),
@@ -62,6 +67,20 @@ export const flowStateSchema = z.object({
     .array(z.string())
     .optional()
     .describe("가장 최근 행동이 붙인 첨부 주소(시안 등, #115). 없으면 생략"),
+  inputs: z
+    .object({
+      by: z.string().describe("적은 사람 — seller · buyer"),
+      values: z.array(
+        z.object({
+          key: z.string(),
+          label: z.string(),
+          type: z.string(),
+          value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]),
+        }),
+      ),
+    })
+    .optional()
+    .describe("이 상태로 오게 한 행동의 입력값(수정 내용 등, #115). 없으면 생략"),
   progress: z.boolean().optional().describe("진행 단계 표시에 넣는 상태인가"),
   fields: z.record(z.string(), flowFieldValueSchema).describe("보는 사람 공개 범위의 커스텀 필드"),
 });
@@ -76,9 +95,63 @@ export const orderItemFlowSchema = z.object({
     .array(z.object({ key: z.string(), dueAt: z.string(), paused: z.boolean() }))
     .describe("걸린 타이머(셀러 보기)"),
   ended: z.boolean(),
+  moveTargets: z
+    .array(
+      z.object({
+        key: z.string(),
+        label: z.string().describe("셀러용 상태 이름"),
+        coreStatus: orderItemStatusSchema.nullable(),
+      }),
+    )
+    .optional()
+    .describe("상태 직접 이동으로 옮길 수 있는 상태(셀러 보기). 흐름이 끝났으면 빈 배열"),
+  branches: z
+    .array(flowStateSchema)
+    .optional()
+    .describe(
+      "활성 위치가 둘 이상(병렬 가지·하위 흐름)이면 각 위치의 상태. `flowState`는 그 가운데 가장 앞 단계다",
+    ),
 });
 export type OrderItemFlow = z.infer<typeof orderItemFlowSchema>;
 
+/** 상태 직접 이동(#115) — 연결선을 지나지 않고 다른 상태로 옮긴다. 블록(재고·환불·송장)은 실행하지 않는다 */
+export const moveFlowStateRequestSchema = z.object({
+  to: z.string().min(1).describe("옮길 상태 키(`moveTargets[].key`)"),
+  reason: z.string().trim().max(200).optional().describe("옮긴 사유(실행 기록에 남는다)"),
+});
+export type MoveFlowStateRequest = z.infer<typeof moveFlowStateRequestSchema>;
+
+export const flowRunStepSchema = z.object({
+  step: z.number().int(),
+  block: z.string().describe("실행한 블록 종류"),
+  edgeId: z.string(),
+  status: z.string(),
+  output: z.record(z.string(), z.unknown()).nullable(),
+  at: z.string(),
+});
+
+/** 흐름 실행 기록 — 사건 하나가 일으킨 전이(시작·행동·사건·시간·이동·취소) */
+export const flowRunSchema = z.object({
+  runId: z.string(),
+  orderItemId: z.string().optional().describe("조회한 주문상품(묶음 진행이면 그 묶음의 하나)"),
+  trigger: z
+    .record(z.string(), z.unknown())
+    .describe(
+      "일으킨 사건 — `type`: start · seller.action · buyer.action · event · timer · move (늘어날 수 있다)",
+    ),
+  status: z.string(),
+  fromState: z.string().nullable(),
+  fromLabel: z.string().nullable().describe("이전 상태의 셀러용 이름"),
+  toState: z.string(),
+  toLabel: z.string().describe("새 상태의 셀러용 이름"),
+  path: z.array(z.string()).describe("지나간 연결선"),
+  error: z.unknown().nullable(),
+  startedAt: z.string(),
+  finishedAt: z.string().nullable(),
+  steps: z.array(flowRunStepSchema).describe("실행한 블록(차례대로)"),
+});
+export type FlowRun = z.infer<typeof flowRunSchema>;
+
 export const flowActionRequestSchema = z.object({
   input: z.record(z.string(), z.unknown()).optional().describe("행동 입력 — 행동의 `input` 폼 키"),
 });
@@ -151,10 +224,45 @@ export const commerceFlowSchema = commerceFlowSummarySchema.extend({
       version: z.number().int(),
       status: z.enum(["DRAFT", "ACTIVE", "LEGACY"]),
       publishedAt: z.string().nullable(),
+      inProgress: z
+        .number()
+        .int()
+        .optional()
+        .describe(
+          "이 버전을 따르는 진행 중 주문상품 흐름 수(묶음 진행은 묶음 하나가 1). 서버는 항상 싣는다",
+        ),
     }),
   ),
 });
 export type CommerceFlow = z.infer<typeof commerceFlowSchema>;
+export type CommerceFlowVersionView = z.infer<typeof commerceFlowVersionViewSchema>;
+
+/** 진행 중 주문을 활성 버전으로 옮기기(#115) — 한 번에 `limit`개까지. 남으면 다시 부른다 */
+export const migrateFlowVersionRequestSchema = z.object({
+  limit: z.number().int().min(1).max(500).optional().describe("한 번에 옮길 흐름 수(기본 100)"),
+});
+export type MigrateFlowVersionRequest = z.infer<typeof migrateFlowVersionRequestSchema>;
+
+export const migrateFlowVersionResultSchema = z.object({
+  fromVersion: z.number().int(),
+  toVersion: z.number().int(),
+  migrated: z.number().int().describe("옮긴 흐름 수"),
+  skipped: z
+    .array(
+      z.object({
+        orderItemIds: z.array(z.string()),
+        state: z.string(),
+        reason: z
+          .string()
+          .describe(
+            "STATE_MISSING 새 버전에 같은 상태가 없음 · CHILD_ACTIVE 진행 중 클레임 · EXTERNAL_PENDING 외부 API 응답 대기 (늘어날 수 있다)",
+          ),
+      }),
+    )
+    .describe("이번에 옮기지 못한 흐름(그 버전에 남는다)"),
+  remaining: z.number().int().describe("아직 이 버전에 남은 진행 중 흐름 수(건너뛴 것 포함)"),
+});
+export type MigrateFlowVersionResult = z.infer<typeof migrateFlowVersionResultSchema>;
 
 export const createCommerceFlowRequestSchema = z.object({
   key: z
@@ -228,3 +336,147 @@ export const saveFlowSecretRequestSchema = z.object({
     .describe("함께 보낼 헤더(인증 등). 값은 암호화해 두고 다시 보여 주지 않는다"),
 });
 export type SaveFlowSecretRequest = z.input<typeof saveFlowSecretRequestSchema>;
+
+/**
+ * 주문 전체 행동 결과(#115) — 같은 행동을 주문의 주문상품마다 실행한다. 한 주문상품의 실패가 다른 주문상품을 되돌리지 않는다(부분 실행).
+ * 묶음 진행이면 한 번 실행이 묶음의 주문상품을 함께 움직인다(COMPLETED로 함께 나온다). 그 행동이 없는 주문상품은 SKIPPED다
+ */
+export const orderFlowActionResultSchema = z.object({
+  orderId: z.string(),
+  key: z.string(),
+  results: z.array(
+    z.object({
+      orderItemId: z.string(),
+      status: z
+        .enum(["COMPLETED", "SKIPPED", "FAILED"])
+        .describe(
+          "COMPLETED 실행 · SKIPPED 이 주문상품에는 그 행동이 없다 · FAILED 실행하다 거절됐다",
+        ),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          "SKIPPED·FAILED의 이유 — 꺼진 이유(EXPIRED·CONDITION·NOT_IN_STATE) 또는 오류 코드",
+        ),
+      message: z.string().optional(),
+    }),
+  ),
+});
+export type OrderFlowActionResult = z.infer<typeof orderFlowActionResultSchema>;
+
+// ── 시뮬레이터·과거 주문 재생(#115 P2) — 초안을 가상 시계로 돌려 본다. 실제 주문·돈·재고는 건드리지 않는다 ─────────────
+
+const simulationEventSchema = z.object({
+  type: z
+    .enum(["start", "seller.action", "buyer.action", "event", "timer"])
+    .describe(
+      "start 결제 승인 · seller.action 셀러 버튼 · buyer.action 구매자 버튼 · event 사건 · timer 타이머 키",
+    ),
+  key: z.string().optional().describe("행동·사건·타이머 키(start는 없음)"),
+});
+
+export const simulateFlowRequestSchema = z.object({
+  startAt: z.iso.datetime({ offset: true }).optional().describe("가상 시계 시작(기본: 지금)"),
+  context: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("식이 읽을 값(item·order·buyer·product). 비우면 견본 주문 값"),
+  steps: z
+    .array(
+      z.union([
+        z.object({ event: simulationEventSchema }),
+        z.object({ advance: z.string().regex(/^P/).describe("시간 경과(ISO 8601 기간)") }),
+      ]),
+    )
+    .min(1)
+    .max(100),
+});
+export type SimulateFlowRequest = z.infer<typeof simulateFlowRequestSchema>;
+
+export const simulationStepSchema = z.object({
+  step: z.number().int(),
+  input: z.record(z.string(), z.unknown()).describe("넣은 사건(`event`) 또는 시간 경과(`advance`)"),
+  at: z.string().describe("이 단계 뒤 가상 시각"),
+  node: z.string().nullable(),
+  label: z.string().nullable().describe("도착 상태의 셀러용 이름"),
+  coreStatus: z.string().optional(),
+  ended: z.boolean(),
+  path: z.array(z.string()).describe("지나간 연결선"),
+  blocks: z.array(z.string()).describe("실행했을 블록 종류"),
+  timers: z.array(z.object({ key: z.string(), dueAt: z.string() })),
+  leaves: z
+    .array(z.object({ node: z.string().nullable(), kind: z.string() }))
+    .optional()
+    .describe("활성 위치가 둘 이상(병렬 가지·하위 흐름)이면 각 위치"),
+  error: z.string().optional().describe("사건이 거절된 이유(NO_TRANSITION 등). 위치는 그대로다"),
+});
+export type SimulationStep = z.infer<typeof simulationStepSchema>;
+
+export const simulateFlowResultSchema = z.object({
+  compiled: z.boolean().describe("초안이 컴파일됐는가. false면 trace가 비고 errors를 고친다"),
+  errors: z.array(flowIssueSchema),
+  trace: z.array(simulationStepSchema),
+});
+export type SimulateFlowResult = z.infer<typeof simulateFlowResultSchema>;
+
+export const replayFlowRequestSchema = z.object({
+  orderItemId: z.string().describe("재생할 주문상품 — 그 흐름의 실행 기록을 초안으로 다시 돌린다"),
+});
+export type ReplayFlowRequest = z.infer<typeof replayFlowRequestSchema>;
+
+export const replayFlowResultSchema = z.object({
+  orderItemId: z.string(),
+  compiled: z.boolean(),
+  errors: z.array(flowIssueSchema),
+  steps: z.array(
+    z.object({
+      runId: z.string(),
+      trigger: z.record(z.string(), z.unknown()),
+      recordedState: z.string().describe("실제로 간 상태"),
+      simulatedState: z.string().nullable().describe("초안으로 돌렸을 때 간 상태"),
+      match: z.boolean(),
+      error: z.string().optional(),
+    }),
+  ),
+  divergedAt: z
+    .number()
+    .int()
+    .nullable()
+    .describe("처음 갈라진 단계(steps 인덱스). 끝까지 같으면 null"),
+  unsupported: z
+    .number()
+    .int()
+    .describe(
+      "재생할 수 없는 기록(상태 직접 이동·버전 옮기기·엔진 밖 취소) 수 — 그 앞까지만 돌린다",
+    ),
+});
+export type ReplayFlowResult = z.infer<typeof replayFlowResultSchema>;
+
+/** 노드·블록 종류 목록(#115) — 흐름을 API·AI로 짤 때 쓸 수 있는 종류와 설정 형식(JSON Schema) */
+export const flowNodeTypesSchema = z.object({
+  nodes: z.array(
+    z.object({
+      type: z.string(),
+      version: z.number().int(),
+      kind: z
+        .string()
+        .describe("state 머묾 · wait 결과를 기다림 · end 종료 · transient 즉시 갈라짐"),
+      outputs: z
+        .array(z.string())
+        .nullable()
+        .describe("고정 결과 이름. 설정에서 나오면(셀러 확인의 버튼) null"),
+      configSchema: z.record(z.string(), z.unknown()).describe("설정 형식(JSON Schema)"),
+    }),
+  ),
+  blocks: z.array(
+    z.object({
+      type: z.string(),
+      version: z.number().int(),
+      effect: z
+        .string()
+        .describe("local 같은 트랜잭션 · afterCommit 커밋 뒤 · external 트랜잭션 밖"),
+      configSchema: z.record(z.string(), z.unknown()),
+    }),
+  ),
+});
+export type FlowNodeTypes = z.infer<typeof flowNodeTypesSchema>;

package/src/schemas/misc.ts

@@ -160,6 +160,8 @@ export const eventTypeSchema = z
     "PRODUCT.OUT_OF_STOCK",
     // 커머스 플로우 알림 블록(이슈 #115). 플로우에 알림 블록을 둔 상점의 구독자에게만 간다
     "ORDER.FLOW_NOTIFICATION",
+    // 커머스 플로우 상태 변경(이슈 #115). 흐름 단계가 바뀔 때마다 간다
+    "ORDER.FLOW_STATE_CHANGED",
   ])
   .describe(
     "웹훅 이벤트 타입. `ORDER.ADDRESS_CHANGE_REQUESTED`는 현재 발송하지 않음(호환을 위해 값만 남았고, 구독해도 이벤트가 오지 않는다)",

package/src/schemas/order.ts

@@ -15,6 +15,11 @@ export const orderSummarySchema = z.object({
   itemCount: z.number().int(),
   totalAmount: z.number().int(),
   representativeStatus: orderItemStatusSchema,
+  progressStatus: orderItemStatusSchema
+    .optional()
+    .describe(
+      "진행 중 주문상품 가운데 가장 앞 단계(취소 제외, 모두 취소면 CANCELED, #115). 섞인 주문에서 아직 기다리는 단계다. 서버는 항상 싣는다",
+    ),
   orderedAt: z.string(),
   testPayment: z
     .boolean()
@@ -162,6 +167,11 @@ export type OrderDiscount = z.infer<typeof orderDiscountSchema>;
 
 export const orderSchema = z.object({
   orderId: z.string(),
+  progressStatus: orderItemStatusSchema
+    .optional()
+    .describe(
+      "진행 중 주문상품 가운데 가장 앞 단계(취소 제외, 모두 취소면 CANCELED, #115). 섞인 주문에서 아직 기다리는 단계다. 서버는 항상 싣는다",
+    ),
   orderNo: commerceNumberField(
     "주문번호(이슈 #107) — 숫자 14자리(YYMMDD KST + 난수 8자리), 전역 유일, 생성 후 바뀌지 않습니다. 전화 CS·ARS용 번호이고 API 경로의 식별자는 여전히 `orderId`입니다. 화면 표기는 `formatOrderNo`(4자리 하이픈)를 쓰십시오",
   ),

package/src/schemas/webhook-event.ts

@@ -399,6 +399,31 @@ export const flowNotificationWebhookEventSchema = z.object({
   data: flowNotificationWebhookEventDataSchema,
 });
 
+/**
+ * 흐름 상태 변경(이슈 #115) — 주문상품의 흐름 상태(노드)가 바뀔 때마다 온다. 공개 상태(`ORDER.*`)가 같아도 상점 흐름의 단계가 바뀌면 온다
+ * (시안 확인 → 제작중). 묶음 진행이면 `orderItemIds`가 여럿이다. 개인정보는 싣지 않는다
+ */
+export const flowStateChangedWebhookEventDataSchema = z.object({
+  orderId: z.string().describe("주문 ID"),
+  orderItemIds: z.array(z.string()).describe("상태가 바뀐 주문상품(묶음 진행이면 여럿)"),
+  flowId: z.string(),
+  flowVersion: z.number().int(),
+  from: z.string().nullable().describe("이전 상태 키. 흐름이 막 시작했으면 null"),
+  to: z.string().describe("새 상태 키"),
+  label: z.string().describe("새 상태의 셀러용 이름"),
+  coreStatus: z
+    .string()
+    .nullable()
+    .describe("새 상태의 공개 상태. 공개 상태를 바꾸지 않는 단계면 null"),
+  changedAt: z.string().describe("바뀐 시각"),
+});
+
+export const flowStateChangedWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("ORDER.FLOW_STATE_CHANGED"),
+  data: flowStateChangedWebhookEventDataSchema,
+});
+
 /** 웹훅 요청 본문. `type`으로 판별하며 `data` 형태가 타입별로 다르다 */
 export const webhookEventSchema = z
   .discriminatedUnion("type", [
@@ -410,6 +435,7 @@ export const webhookEventSchema = z
     reviewWebhookEventSchema,
     productOutOfStockWebhookEventSchema,
     flowNotificationWebhookEventSchema,
+    flowStateChangedWebhookEventSchema,
   ])
   .describe(
     "웹훅 요청 본문 (얇은 이벤트). 개인정보를 싣지 않으며 `data`의 id로 관리 API를 조회한다",