@sayren/store-sdk 0.38.0 → 0.40.0

package/src/schemas/commerce-flow.ts

@@ -357,12 +357,22 @@ export const saveFlowDraftRequestSchema = z.object({
 });
 export type SaveFlowDraftRequest = z.infer<typeof saveFlowDraftRequestSchema>;
 
-const flowIssueSchema = z.object({
+export const flowIssueSchema = z.object({
   code: z.string(),
   message: z.string(),
   nodeId: z.string().optional(),
   edgeId: z.string().optional(),
+  pointer: z
+    .string()
+    .optional()
+    .describe(
+      "위치(JSON Pointer) — 그래프 문서 안(`/nodes/3/config/buttons/0/key`). 조작 오류(`OP_*`)는 그 조작 안 위치",
+    ),
+  opIndex: z.number().int().optional().describe("조작 묶음에서 몇 번째 조작(0부터)에서 났는가"),
+  hint: z.string().optional().describe("고치는 법·후보(가능한 값·비슷한 이름)"),
+  expected: z.unknown().optional().describe("그 위치의 설정 형식(JSON Schema 조각)"),
 });
+export type FlowIssue = z.infer<typeof flowIssueSchema>;
 
 export const commerceFlowCheckSchema = z.object({
   publishable: z.boolean().describe("게시를 막는 오류(실행 불가·공개 계약·한도)가 없다"),
@@ -371,6 +381,130 @@ export const commerceFlowCheckSchema = z.object({
 });
 export type CommerceFlowCheck = z.infer<typeof commerceFlowCheckSchema>;
 
+// ── 흐름 조작 묶음(#120) — 노드·연결선 단위로 고친다. `POST /commerce-flows/{flowId}/draft/operations`, `If-Match` 필수 ─────────────
+
+/** JSON Pointer(`/`로 시작) */
+const flowPointerSchema = z.string().regex(/^\//, "JSON Pointer(/로 시작)여야 합니다");
+
+const flowPointerSetSchema = z
+  .record(flowPointerSchema, z.unknown())
+  .describe(
+    "JSON Pointer → 값. 그 위치의 값을 통째로 바꾼다(합치지 않는다). 배열(버튼 등)은 배열 전체를 넣는다",
+  );
+const flowPointerUnsetSchema = z.array(flowPointerSchema).describe("지울 위치(JSON Pointer) 목록");
+
+/** 흐름 노드 id — 영문으로 시작, 영문·숫자·_·- */
+export const flowNodeIdSchema = z
+  .string()
+  .regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "노드 id는 영문으로 시작하고 영문·숫자·_·-만 씁니다");
+
+/**
+ * 조작 하나(#120) — 원천은 여기 하나다(api 본문 검증과 flow-spec `applyFlowOps`가 같은 스키마를 쓴다). 모르는 키는 400이다
+ * (지우고 성공하면 잘못 쓴 조작이 아무 일도 하지 않은 채 통과한다)
+ */
+export const flowDraftOperationSchema = z.discriminatedUnion("op", [
+  z
+    .strictObject({
+      op: z.literal("addNode"),
+      id: flowNodeIdSchema.describe("새 노드 id(영문으로 시작, 영문·숫자·_·-)"),
+      type: z.string().min(1).describe("노드 종류(`GET /flow-node-types/{type}`)"),
+      config: z.record(z.string(), z.unknown()).optional().describe("노드 설정"),
+      position: z
+        .strictObject({ x: z.number(), y: z.number() })
+        .optional()
+        .describe("없으면 서버가 앞 노드 오른쪽에 둔다"),
+    })
+    .describe("노드 더하기 — version·outputs는 서버가 채운다"),
+  z
+    .strictObject({
+      op: z.literal("updateNode"),
+      id: z.string().min(1),
+      set: flowPointerSetSchema.optional().describe("`/config/…`·`/position` 아래만"),
+      unset: flowPointerUnsetSchema.optional(),
+    })
+    .describe("노드 고치기"),
+  z
+    .strictObject({ op: z.literal("removeNode"), id: z.string().min(1) })
+    .describe("노드 지우기 — 드나드는 연결선도 지운다. 시작 노드는 400(먼저 setStart)"),
+  z
+    .strictObject({
+      op: z.literal("connect"),
+      id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "연결선 id. 주면 같은 묶음의 updateEdge·disconnect가 가리킬 수 있다. 없으면 서버가 만든다",
+        ),
+      from: z.string().min(1).describe("`노드` 또는 `노드:출력`"),
+      to: z.string().min(1),
+      on: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("조건(트리거). 출력 연결선·즉시 노드에서는 두지 않는다"),
+      guard: z.string().optional().describe("조건식(CEL)"),
+      do: z.array(z.record(z.string(), z.unknown())).optional().describe("지날 때 실행할 블록"),
+    })
+    .describe("연결선 잇기"),
+  z
+    .strictObject({
+      op: z.literal("updateEdge"),
+      id: z.string().min(1),
+      set: flowPointerSetSchema.optional().describe("`/from`·`/to`·`/on`·`/guard`·`/do` 아래만"),
+      unset: flowPointerUnsetSchema.optional(),
+    })
+    .describe("연결선 고치기"),
+  z.strictObject({ op: z.literal("disconnect"), id: z.string().min(1) }).describe("연결선 지우기"),
+  z.strictObject({ op: z.literal("setStart"), id: z.string().min(1) }).describe("시작 노드 바꾸기"),
+  z
+    .strictObject({
+      op: z.literal("setDefinition"),
+      set: z
+        .strictObject({
+          progression: z.enum(["ITEM", "ORDER_GROUP"]).optional(),
+          groupClaim: z.enum(["CONTINUE", "PAUSE"]).optional(),
+          fulfillmentMethods: z
+            .array(z.enum(["CARRIER", "DIRECT", "PICKUP", "PROVIDED"]))
+            .min(1)
+            .optional(),
+        })
+        .optional(),
+      unset: z.array(z.enum(["progression", "groupClaim", "fulfillmentMethods"])).optional(),
+    })
+    .describe("흐름 설정(진행 단위·묶음 클레임·이행 방식) 바꾸기"),
+]);
+export type FlowDraftOperation = z.infer<typeof flowDraftOperationSchema>;
+
+export const applyFlowOperationsRequestSchema = z.object({
+  operations: z
+    .array(flowDraftOperationSchema)
+    .min(1)
+    .describe(
+      "차례대로 적용한다. 묶음은 원자적이다 — 하나라도 형식이 틀리면 아무것도 바꾸지 않는다(400)",
+    ),
+});
+export type ApplyFlowOperationsRequest = z.infer<typeof applyFlowOperationsRequestSchema>;
+
+export const flowOperationsResultSchema = z.object({
+  revision: z.number().int().describe("저장 뒤 초안 revision — 다음 조작의 If-Match"),
+  changed: z.object({
+    nodes: z.array(z.string()).describe("더하거나 바꾼 노드"),
+    edges: z.array(z.string()).describe("더하거나 바꾼 연결선"),
+    removedNodes: z.array(z.string()),
+    removedEdges: z.array(z.string()).describe("지운 연결선(노드와 함께 지워진 것 포함)"),
+    removedActions: z
+      .array(z.string())
+      .describe(
+        "그래프에서 사라진 셀러·구매자 행동(`seller.action:CONFIRM_ORDER`). 셀러에게 확인받는다",
+      ),
+  }),
+  issues: z
+    .array(flowIssueSchema)
+    .describe("게시를 막는 문제. 저장은 됐다(초안은 미완성일 수 있다)"),
+  warnings: z.array(flowIssueSchema).describe("업무 논리 경고 — 게시를 막지 않는다"),
+});
+export type FlowOperationsResult = z.infer<typeof flowOperationsResultSchema>;
+
 // ── 흐름 해석(이슈 #115) — 상품의 흐름 → 카테고리(맨 아래)의 흐름 → 기본 흐름. 할당 규칙은 없앴다 ─────────────────
 
 export const resolvedFlowSchema = z.object({
@@ -527,6 +661,75 @@ export const replayFlowResultSchema = z.object({
 });
 export type ReplayFlowResult = z.infer<typeof replayFlowResultSchema>;
 
+// ── 요소 단위 읽기(#120) — 흐름 전체 대신 노드·연결선을 따로 읽는다. 응답 크기가 흐름이 아니라 요소에 비례한다 ─────────────
+
+const flowDraftRevisionSchema = z
+  .number()
+  .int()
+  .describe(
+    "초안 revision — 조작의 If-Match 값. 초안이 없으면 게시 버전을 0으로 보여 준다(첫 쓰기가 초안을 연다)",
+  );
+
+export const flowDraftNodesSchema = z.object({
+  revision: flowDraftRevisionSchema,
+  start: z.string().describe("시작 노드 id"),
+  nodes: z.array(
+    z.object({
+      id: z.string(),
+      type: z.string(),
+      label: z.string().nullable().describe("셀러용 이름(`config.label.seller`). 없으면 null"),
+      kind: z
+        .string()
+        .nullable()
+        .describe(
+          "start · state · wait · end · transient · call · fork · join (늘어날 수 있다). 모르는 종류면 null",
+        ),
+      outputs: z
+        .array(z.string())
+        .describe("출력 이름 — 연결선은 `노드:출력`으로 가리킨다. 없으면 `노드`로 가리킨다"),
+    }),
+  ),
+});
+export type FlowDraftNodes = z.infer<typeof flowDraftNodesSchema>;
+
+export const flowDraftNodeSchema = z.object({
+  revision: flowDraftRevisionSchema,
+  node: z
+    .object({
+      id: z.string(),
+      type: z.string(),
+      version: z.number().int(),
+      config: z.record(z.string(), z.unknown()),
+      outputs: z.array(z.string()).optional(),
+      position: z.object({ x: z.number(), y: z.number() }).optional(),
+    })
+    .describe("노드 하나(설정 전체)"),
+  kind: z.string().nullable(),
+  outputs: z.array(z.string()).describe("설정에서 계산한 출력"),
+  start: z.boolean().describe("시작 노드인가"),
+  incoming: z.array(z.string()).describe("들어오는 연결선 id"),
+  outgoing: z.array(z.string()).describe("나가는 연결선 id"),
+});
+export type FlowDraftNode = z.infer<typeof flowDraftNodeSchema>;
+
+export const flowDraftEdgesSchema = z.object({
+  revision: flowDraftRevisionSchema,
+  edges: z.array(
+    z.object({
+      id: z.string(),
+      from: z.string().describe("`노드` 또는 `노드:출력`"),
+      to: z.string(),
+      on: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("조건 — `type`: seller.action · buyer.action · event · timer · immediate"),
+      guard: z.string().optional().describe("조건식(CEL)"),
+      do: z.array(z.record(z.string(), z.unknown())).optional().describe("지날 때 실행할 블록"),
+    }),
+  ),
+});
+export type FlowDraftEdges = z.infer<typeof flowDraftEdgesSchema>;
+
 /** 노드·블록 종류 목록(#115) — 흐름을 API·AI로 짤 때 쓸 수 있는 종류와 설정 형식(JSON Schema) */
 export const flowNodeTypesSchema = z.object({
   nodes: z.array(
@@ -571,3 +774,99 @@ export const flowNodeTypesSchema = z.object({
     .describe("노드 권한 표에 켤 수 있는 플랫폼 행동(#115) — 편집기는 이 목록으로 행을 그린다"),
 });
 export type FlowNodeTypes = z.infer<typeof flowNodeTypesSchema>;
+
+// ── 작성 안내(#120) — 흐름을 노드·연결선 단위로 짤 때 읽는다. 종류 하나의 설정 형식은 따로 읽는다 ─────────────
+
+export const flowAuthoringGuideSchema = z.object({
+  nodes: z
+    .array(
+      z.object({
+        type: z.string(),
+        name: z.string().describe("표시 이름"),
+        kind: z
+          .string()
+          .describe("start · state · wait · end · transient · call · fork · join (늘어날 수 있다)"),
+        outputs: z.array(z.string()).nullable().describe("고정 출력. 설정에서 나오면 null"),
+        description: z.string(),
+      }),
+    )
+    .describe("노드 종류 — 설정 형식은 `GET /flow-node-types/{type}`"),
+  blocks: z.array(
+    z.object({
+      type: z.string(),
+      effect: z.string().describe("local · afterCommit · external"),
+      description: z.string(),
+    }),
+  ),
+  triggers: z
+    .array(z.object({ type: z.string(), format: z.string(), description: z.string() }))
+    .describe("연결선 조건(on) 형식"),
+  context: z
+    .record(z.string(), z.string())
+    .describe("식·안내문 틀이 읽을 수 있는 값 — 점 경로 → 타입(int·string·bool·timestamp·dyn …)"),
+  functions: z
+    .array(z.object({ name: z.string(), signature: z.string(), doc: z.string() }))
+    .describe("식 함수"),
+  templateFilters: z.array(z.string()).describe("안내문 틀 필터(`{{ 경로 | 필터 }}`)"),
+  rules: z.array(z.string()).describe("그래프 규칙"),
+  expressionExamples: z.array(z.object({ expr: z.string(), description: z.string() })),
+  operationExample: z
+    .array(z.record(z.string(), z.unknown()))
+    .describe("조작 묶음 예시(`POST /commerce-flows/{flowId}/draft/operations`의 operations)"),
+});
+export type FlowAuthoringGuide = z.infer<typeof flowAuthoringGuideSchema>;
+
+export const flowNodeTypeDetailSchema = z.object({
+  type: z.string(),
+  category: z.string().describe("node · block"),
+  version: z.number().int().describe("최신 버전 — 조작이 노드를 더할 때 이 버전을 쓴다"),
+  kind: z.string().nullable().describe("노드 성격(블록은 null)"),
+  effect: z.string().nullable().describe("블록 실행 성격(노드는 null)"),
+  outputs: z.array(z.string()).nullable().describe("고정 출력. 설정에서 나오면 null"),
+  name: z.string(),
+  description: z.string(),
+  configSchema: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .describe(
+      "설정 형식(JSON Schema). 공통 설정(이름·권한·입력 칸·식 참조)은 `$defs`. 옮길 수 없으면 null",
+    ),
+  example: z.record(z.string(), z.unknown()).describe("검사를 통과하는 예시 설정"),
+});
+export type FlowNodeTypeDetail = z.infer<typeof flowNodeTypeDetailSchema>;
+
+// ── 편집권(#120) — 흐름 초안은 한 번에 한 주체(사람·AI 도우미·외부 에이전트)만 고친다 ─────────────
+
+export const flowEditSessionViewSchema = z.object({
+  revision: z.number().int().describe("지금 초안 revision(초안이 없으면 0)"),
+  session: z
+    .object({
+      holder: z.object({
+        kind: z
+          .string()
+          .describe("USER 사람 · AI_ASSISTANT AI 도우미 · AGENT 외부 에이전트 (늘어날 수 있다)"),
+        name: z.string().nullable(),
+      }),
+      expiresAt: z.string().describe("이때까지 연장하지 않으면 풀린다(ISO 8601)"),
+      mine: z.boolean().describe("요청한 주체의 편집권인가"),
+    })
+    .nullable()
+    .describe("지금 편집권. 비어 있으면 null — 누구든 첫 쓰기가 잡는다"),
+  channel: z
+    .object({ streamId: z.string(), streamUrl: z.string(), streamToken: z.string() })
+    .nullable()
+    .describe(
+      "흐름 채널 구독(SSE, `Authorization: Bearer streamToken`) — session·ops·saved·released 이벤트. 중계가 없는 환경이면 null",
+    ),
+});
+export type FlowEditSessionView = z.infer<typeof flowEditSessionViewSchema>;
+
+export const claimFlowEditSessionRequestSchema = z.object({
+  takeover: z
+    .boolean()
+    .optional()
+    .describe(
+      "다른 주체가 잡고 있어도 넘겨받는다. 앞 주체의 저장하지 않은 수정은 사라지고, AI 도우미면 그 실행이 멈춘다",
+    ),
+});
+export type ClaimFlowEditSessionRequest = z.infer<typeof claimFlowEditSessionRequestSchema>;

package/src/schemas/shipping-policy.ts

@@ -180,7 +180,7 @@ export type RemoteArea = z.infer<typeof remoteAreaSchema>;
  * 도로명주소·건물관리번호 단위 판정은 후속 과제다.
  *
  * 범위는 **닫힌 구간**(`from` ≤ zip ≤ `to`)이고 겹치지 않는다. 앞에서부터 처음 맞는 항목을 쓴다.
- * 순서는 상점 플랫폼 「추가 배송비 지역」 표의 행 순서이기도 하다(`remoteAreaGroups`). 제주를 먼저 두고
+ * 순서는 docs `guides/shipping-fees.mdx` 「제주·도서산간 추가 배송비」 표의 행 순서이기도 하다. 제주를 먼저 두고
  * 도서산간은 우편번호 오름차순으로 둔다.
  */
 export const REMOTE_AREA_ZIP_RANGES: ReadonlyArray<{

package/src/schemas/storefront-hosting.ts

@@ -25,7 +25,6 @@ import { RESERVED_STORE_CODES } from "./store";
  * - 409 `STOREFRONT_NO_ROLLBACK_TARGET` — 되돌릴 이전 발행 버전이 없다
  * - 409 `STOREFRONT_NOT_READY` — 공개 전환: 판매 중인 상품(샘플 제외)이 없다(이슈 #70). 상품을 등록한 뒤 공개한다
  * - 409 `TEMPLATE_CHANGE_NOT_SUPPORTED` — 템플릿 변경(`POST /v1/storefront/site/template`, 폐기)은 항상 이 오류다
- * - 400 `STOREFRONT_SLUG_CONFIRM_MISMATCH` — 호스팅 끄기 확인 입력이 현재 슬러그와 다르다
  * - 503 `STOREFRONT_PREVIEW_NOT_CONFIGURED` — 미리보기 서명 키가 설정되지 않았다
  *
  * 편집(M2b, `/v1/storefront/site/editing`·`files/**`·`checks/**`·`verify`·`builds/**`, 버전 만들기):
@@ -551,9 +550,13 @@ export const setStorefrontVisibilityRequestSchema = z.object({
 });
 export type SetStorefrontVisibilityRequest = z.infer<typeof setStorefrontVisibilityRequestSchema>;
 
-/** 호스팅 끄기 — 사이트를 닫고(`CLOSED`) 슬러그를 보류한다. 확인 입력은 현재 슬러그다 */
+/** 호스팅 끄기 — 사이트를 닫고(`CLOSED`) 슬러그를 보류한다. 확인 입력은 받지 않는다(2026-10-22) */
 export const disableStorefrontHostingRequestSchema = z.object({
-  confirmSlug: z.string().min(1).describe("확인 입력 — 현재 슬러그"),
+  confirmSlug: z
+    .string()
+    .max(200)
+    .optional()
+    .describe("쓰지 않는다 — 보내도 무시한다(옛 확인 입력)"),
 });
 export type DisableStorefrontHostingRequest = z.infer<typeof disableStorefrontHostingRequestSchema>;
 
@@ -946,7 +949,12 @@ export const storefrontEditSessionStatusSchema = z
   .describe("`STARTING` 띄우는 중 · `RUNNING` 사용 중");
 
 /** 편집 환경을 띄우는 단계 — 상점 플랫폼 진행 표시용이다. 값은 늘어날 수 있다 */
-export const STOREFRONT_EDIT_START_STAGES = ["CONTAINER", "RESTORE", "DEV_SERVER"] as const;
+export const STOREFRONT_EDIT_START_STAGES = [
+  "CONTAINER",
+  "RESTORE",
+  "INSTALL",
+  "DEV_SERVER",
+] as const;
 
 export const storefrontEditSessionSchema = z.object({
   sessionId: z.string(),
@@ -955,7 +963,7 @@ export const storefrontEditSessionSchema = z.object({
     .string()
     .nullable()
     .describe(
-      "`STARTING`일 때 지금 단계 (`CONTAINER` 컨테이너 기동 · `RESTORE` 작업 트리 복원 · `DEV_SERVER` 개발 서버 기동). 늘어날 수 있다. `RUNNING`이면 null",
+      "`STARTING`일 때 지금 단계 (`CONTAINER` 컨테이너 기동 · `RESTORE` 작업 트리 복원 · `INSTALL` 의존성 설치(`pnpm-lock.yaml`이 템플릿과 다를 때만) · `DEV_SERVER` 개발 서버 기동). 늘어날 수 있다. `RUNNING`이면 null",
     ),
   startedAt: z.string().describe("연 시각 (ISO 8601)"),
   lastEditedAt: z
@@ -1004,6 +1012,13 @@ export const storefrontGitMergeSchema = z.object({
     .describe(
       "합친 뒤에도 발행 전 작업이 지금 운영 브랜치 위가 아니다(충돌·취소면 true). false면 버전을 만들어 발행할 수 있다",
     ),
+  // 옛 api 응답에는 없다
+  dependenciesChanged: z
+    .boolean()
+    .optional()
+    .describe(
+      "합친 운영 브랜치가 `package.json`·`pnpm-lock.yaml`을 바꿔 의존성을 다시 검사하고 편집 환경을 다시 띄웠다(`STARTING`, 설치가 실패하면 편집 상태 `lastFailure`)",
+    ),
 });
 export type StorefrontGitMerge = z.infer<typeof storefrontGitMergeSchema>;
 
@@ -1028,6 +1043,25 @@ export const storefrontDevLogsSchema = z.object({
 });
 export type StorefrontDevLogs = z.infer<typeof storefrontDevLogsSchema>;
 
+/**
+ * 편집 환경 시작 실패(#125) — 작업 트리 `pnpm-lock.yaml`이 템플릿과 다르면 편집 환경은 빌드와 같은 의존성 정책으로 설치한 뒤 개발 서버를
+ * 띄운다. 설치가 실패하면 미리보기 대신 이 원인이 남는다
+ */
+export const storefrontEditFailureSchema = z.object({
+  code: z
+    .string()
+    .describe(
+      "실패 코드 (`INSTALL_FAILED` 설치 실패 · `INSTALL_TOO_LARGE` 설치 크기 상한 초과 · `DEPENDENCIES_CHANGED` 검사 뒤 의존성 파일이 바뀜 · `DEPENDENCIES_UNCHECKED` 의존성 검사 없음 · `START_TIMEOUT`·`CAPACITY_EXHAUSTED`·`CONTAINER_ERROR`·`RESTART_FAILED` 등, 늘어날 수 있다)",
+    ),
+  message: z.string().describe("사용자용 안내"),
+  logTail: z
+    .string()
+    .nullable()
+    .describe("설치 출력 끝부분(레지스트리가 거절한 요청 포함). 설치 단계 실패가 아니면 null"),
+  failedAt: z.string().nullable().describe("닫힌 시각 (ISO 8601)"),
+});
+export type StorefrontEditFailure = z.infer<typeof storefrontEditFailureSchema>;
+
 export const storefrontEditingSchema = z.object({
   enabled: z.boolean().describe("편집을 쓸 수 있는가 (Sandbox 설정)"),
   session: storefrontEditSessionSchema
@@ -1046,6 +1080,13 @@ export const storefrontEditingSchema = z.object({
       .describe("템플릿에서 한 번이라도 고쳤는가 (사이트 `sourceMode`가 `CUSTOM`)"),
     lastEditedAt: z.string().nullable().describe("마지막으로 파일을 바꾼 시각"),
   }),
+  // 옛 api 응답에는 없다 — 새 SDK가 배포 전 api와 함께 쓰여도 깨지지 않게 선택 필드다
+  lastFailure: storefrontEditFailureSchema
+    .nullable()
+    .optional()
+    .describe(
+      "편집 환경이 꺼져 있고 마지막 편집 환경이 시작하지 못하고(또는 다시 띄우지 못하고) 닫혔으면 그 원인. 다시 켜면 사라진다. 없으면 null",
+    ),
 });
 export type StorefrontEditing = z.infer<typeof storefrontEditingSchema>;