@sayren/store-sdk 0.30.13 → 0.30.14

package/src/schemas/ai.ts

@@ -0,0 +1,376 @@
+import { z } from "zod";
+
+/**
+ * 상점 플랫폼 AI 채팅(이슈 #124) — 대화·메시지·실행과 실행 이벤트 스트림의 계약.
+ *
+ * 상점 플랫폼 전용이다(`@ConsoleOnly`, 공개 OpenAPI 문서 제외). 메시지를 보내면 api가 실행(run)을 만들어 202로 `streamId`를 돌려주고,
+ * 응답은 별도 중계(`streamUrl`, SSE)로 받는다. 실행은 브라우저와 무관하게 서버에서 끝까지 돈다 — 다시 열면 진행 중 실행의 스트림에
+ * 처음부터 다시 붙거나(보관 1시간) 확정된 메시지를 읽는다.
+ */
+
+/** 첨부 하나 — 업로드(`POST /v1/uploads`, 목적 `ai-attachment`)가 돌려준 공개 주소 */
+export const aiAttachmentSchema = z.object({
+  url: z.string().url().max(2048),
+  name: z.string().trim().min(1).max(200),
+  mediaType: z.string().trim().min(1).max(100).describe("image/* 또는 application/pdf"),
+});
+export type AiAttachment = z.infer<typeof aiAttachmentSchema>;
+
+export const AI_MESSAGE_MAX_CHARS = 8_000;
+export const AI_MESSAGE_MAX_ATTACHMENTS = 5;
+
+/**
+ * 편집 미리보기에서 고른 요소(#65) — 미리보기 안 선택 스크립트가 만든 값이라 사이트 코드가 꾸밀 수 있다. api는 모델에 넘길 때 데이터로
+ * 감싼다. `source`는 그 컴포넌트를 **사용한** 위치다(작업 트리 상대 경로). React 개발 정보가 없으면 null이다
+ */
+export const aiPreviewSelectionSchema = z.object({
+  component: z.string().max(120).nullable(),
+  source: z
+    .object({
+      path: z.string().max(300),
+      line: z.number().int().positive().max(1_000_000),
+      column: z.number().int().positive().max(100_000).optional(),
+    })
+    .nullable(),
+  tag: z.string().max(40),
+  text: z.string().max(200),
+  pagePath: z.string().max(500),
+});
+export type AiPreviewSelection = z.infer<typeof aiPreviewSelectionSchema>;
+
+/** 실행 상태 — 끝난 상태는 `DONE`·`FAILED`·`CANCELLED`다 */
+export const aiRunStatusSchema = z.enum([
+  "QUEUED",
+  "RUNNING",
+  "CANCEL_REQUESTED",
+  "DONE",
+  "FAILED",
+  "CANCELLED",
+]);
+export type AiRunStatus = z.infer<typeof aiRunStatusSchema>;
+
+export const AI_RUN_ACTIVE_STATUSES: readonly AiRunStatus[] = [
+  "QUEUED",
+  "RUNNING",
+  "CANCEL_REQUESTED",
+];
+
+/** 진행 중 실행의 스트림 접속 정보. `streamToken`은 이 스트림 하나만 읽는 단기 자격(Bearer)이다 */
+export const aiStreamAccessSchema = z.object({
+  streamId: z.string(),
+  streamUrl: z.string().url(),
+  streamToken: z.string(),
+});
+export type AiStreamAccess = z.infer<typeof aiStreamAccessSchema>;
+
+export const aiRunSchema = z.object({
+  id: z.string().describe("실행 id = streamId"),
+  status: aiRunStatusSchema,
+  errorCode: z.string().nullable(),
+  createdAt: z.string(),
+  finishedAt: z.string().nullable(),
+});
+export type AiRun = z.infer<typeof aiRunSchema>;
+
+/**
+ * 화면에 그리는 메시지 조각. 모델 원문(tool_use 블록 등)은 api가 보관하고 화면에는 이 형태만 준다.
+ * - `text`: 글
+ * - `tool`: 도구 호출 한 번(이름은 사람이 읽는 라벨, 결과 요약·링크)
+ * - `choices`: 선택지 버튼(가장 최근 것만 누를 수 있다)
+ * - `attachment`: 사용자가 올린 첨부
+ * - `approval`: 승인 대기로 남은 쓰기
+ */
+export const aiMessagePartSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), text: z.string() }),
+  z.object({
+    type: z.literal("tool"),
+    toolCallId: z.string(),
+    name: z.string(),
+    label: z.string(),
+    status: z.enum(["ok", "error", "unknown"]),
+    summary: z.string().nullable(),
+  }),
+  z.object({
+    type: z.literal("choices"),
+    question: z.string(),
+    options: z
+      .array(z.object({ label: z.string(), value: z.string() }))
+      .min(1)
+      .max(6),
+  }),
+  z.object({ type: z.literal("attachment"), attachment: aiAttachmentSchema }),
+  /** 공개 뒤 승인이 필요한 쓰기를 승인 요청으로 남겼다(셀러가 승인함에서 결정한다) */
+  z.object({ type: z.literal("approval"), approvalId: z.string(), title: z.string() }),
+  /** 사용자가 미리보기에서 고른 요소(#65) */
+  z.object({ type: z.literal("selection"), selection: aiPreviewSelectionSchema }),
+]);
+export type AiMessagePart = z.infer<typeof aiMessagePartSchema>;
+
+export const aiMessageSchema = z.object({
+  id: z.string(),
+  role: z.enum(["user", "assistant"]),
+  parts: z.array(aiMessagePartSchema),
+  runId: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type AiMessage = z.infer<typeof aiMessageSchema>;
+
+export const aiConversationSummarySchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type AiConversationSummary = z.infer<typeof aiConversationSummarySchema>;
+
+export const aiConversationSchema = aiConversationSummarySchema.extend({
+  messages: z.array(aiMessageSchema),
+  /** 진행 중 실행(없으면 null) — 스트림에 다시 붙을 때 쓴다 */
+  activeRun: aiRunSchema.extend({ stream: aiStreamAccessSchema }).nullable(),
+  /** 마지막 실행(진행 중이 아니면 결과 표시용) */
+  lastRun: aiRunSchema.nullable(),
+});
+export type AiConversation = z.infer<typeof aiConversationSchema>;
+
+export const createAiConversationRequestSchema = z.object({
+  /** 웹사이트에서 남긴 초안(#124 M2) — 연결한 사용자만 쓴다. 주면 첫 메시지로 실행을 시작한다 */
+  draftId: z.string().max(64).optional(),
+});
+export type CreateAiConversationRequest = z.infer<typeof createAiConversationRequestSchema>;
+
+export const createAiConversationResponseSchema = z.object({
+  conversation: aiConversationSummarySchema,
+  /** `draftId`로 시작했으면 첫 실행 */
+  run: aiStreamAccessSchema.nullable(),
+});
+export type CreateAiConversationResponse = z.infer<typeof createAiConversationResponseSchema>;
+
+export const sendAiMessageRequestSchema = z
+  .object({
+    text: z.string().trim().max(AI_MESSAGE_MAX_CHARS),
+    attachments: z.array(aiAttachmentSchema).max(AI_MESSAGE_MAX_ATTACHMENTS).default([]),
+    /** 선택지 버튼으로 보낸 답이면 그 값(화면 표시는 `text`) */
+    choice: z.string().max(200).optional(),
+    /** 편집 미리보기에서 고른 요소(#65) — 모델은 이 요소를 기준으로 고친다 */
+    selection: aiPreviewSelectionSchema.optional(),
+  })
+  .refine((body) => body.text.length > 0 || body.attachments.length > 0, {
+    message: "내용이나 첨부가 있어야 합니다",
+  });
+export type SendAiMessageRequest = z.input<typeof sendAiMessageRequestSchema>;
+
+export const sendAiMessageResponseSchema = aiStreamAccessSchema.extend({
+  messageId: z.string(),
+});
+export type SendAiMessageResponse = z.infer<typeof sendAiMessageResponseSchema>;
+
+/**
+ * AI가 바꾸는 화면 영역 — 쓰기 도구가 시작되면 이벤트에 싣고, 패널이 그 화면으로 옮겨 반영된 데이터를 다시 읽는다(셀러가 AI가 하는 일을 같이 본다).
+ * 경로는 상점 플랫폼이 정한다(영역 → 라우트). `id`가 있으면 상세 화면이다
+ */
+export const aiFocusAreaSchema = z.enum([
+  "products",
+  "categories",
+  "collections",
+  "option_sets",
+  "coupons",
+  "points",
+  "orders",
+  "claims",
+  "customers",
+  "inquiries",
+  "customer_inquiries",
+  "store_settings",
+  "shipping",
+  "addresses",
+  "payments",
+  "login",
+  "members",
+  "order_flows",
+  "webhooks",
+  "storefront",
+]);
+export type AiFocusArea = z.infer<typeof aiFocusAreaSchema>;
+
+export const aiFocusSchema = z.object({
+  area: aiFocusAreaSchema,
+  id: z.string().optional(),
+});
+export type AiFocus = z.infer<typeof aiFocusSchema>;
+
+// ─── 작업 트리 변경·되돌리기(#65) ─────────────────────────────────────────
+// AI 실행이 스토어프론트 작업 트리를 바꾸면 경로마다 이전·이후를 남긴다. 셀러는 실행 단위로 되돌린다(전부 아니면 전무).
+
+/** 변경 기록 보관 기간 — 지나면 내용을 비우고 되돌릴 수 없다(410 `AI_RUN_CHANGES_EXPIRED`) */
+export const AI_RUN_FILE_CHANGES_RETENTION_DAYS = 7;
+
+/**
+ * 실행 하나의 변경 상태
+ * - `APPLIED`: 되돌릴 수 있다(진행 중 실행이 없을 때)
+ * - `INCOMPLETE`: 결과를 모르는 쓰기·이전 내용이 너무 큰 경로가 있다(되돌릴 수 없다)
+ * - `REVERTING`·`REVERTED`·`REVERT_UNKNOWN`(되돌리기 결과를 모름 — 다시 하지 않는다)·`EXPIRED`
+ */
+export const aiRunChangesStatusSchema = z.enum([
+  "APPLIED",
+  "INCOMPLETE",
+  "REVERTING",
+  "REVERTED",
+  "REVERT_UNKNOWN",
+  "EXPIRED",
+]);
+export type AiRunChangesStatus = z.infer<typeof aiRunChangesStatusSchema>;
+
+export const aiFileChangeKindSchema = z.enum(["created", "modified", "deleted"]);
+export type AiFileChangeKind = z.infer<typeof aiFileChangeKindSchema>;
+
+export const aiRunChangesSchema = z.object({
+  runId: z.string(),
+  status: aiRunChangesStatusSchema,
+  files: z.array(
+    z.object({
+      path: z.string(),
+      change: aiFileChangeKindSchema.describe("결과를 모르는 경로는 `modified`로 보인다"),
+    }),
+  ),
+});
+export type AiRunChanges = z.infer<typeof aiRunChangesSchema>;
+
+/** `GET /v1/ai/conversations/{id}/file-changes` — 대화의 실행별 변경(실행 만든 순) */
+export const aiConversationFileChangesSchema = z.object({
+  runs: z.array(aiRunChangesSchema),
+});
+export type AiConversationFileChanges = z.infer<typeof aiConversationFileChangesSchema>;
+
+/** `GET /v1/ai/runs/{runId}/file-changes` — 변경 보기. 텍스트가 아닌 파일·보관이 끝난 내용은 null이다(diff는 화면이 계산한다) */
+export const aiRunFileDiffSchema = aiRunChangesSchema.extend({
+  files: z.array(
+    z.object({
+      path: z.string(),
+      change: aiFileChangeKindSchema,
+      before: z.string().nullable(),
+      after: z.string().nullable(),
+      binary: z.boolean(),
+    }),
+  ),
+});
+export type AiRunFileDiff = z.infer<typeof aiRunFileDiffSchema>;
+
+/**
+ * `POST /v1/ai/runs/{runId}/revert` — 실행이 바꾼 경로를 그 전 내용으로 한 번에 돌린다. 오류: 409 `AI_RUN_IN_PROGRESS`(대화에 진행 중 실행),
+ * 409 `AI_RUN_REVERT_CONFLICT`(`details.conflicts` — 그 뒤 바뀐 경로·결과를 모르는 쓰기), 409 `AI_RUN_ALREADY_REVERTED`,
+ * 410 `AI_RUN_CHANGES_EXPIRED`, 404 `AI_RUN_CHANGES_NOT_FOUND`, 502 `AI_RUN_REVERT_UNKNOWN`(결과를 모름 — 다시 하지 않는다)
+ */
+export const aiRunRevertResultSchema = z.object({
+  runId: z.string(),
+  status: z.literal("REVERTED"),
+  paths: z.array(z.string()),
+});
+export type AiRunRevertResult = z.infer<typeof aiRunRevertResultSchema>;
+
+/** 409 `AI_RUN_REVERT_CONFLICT`의 `error.details` */
+export const aiRunRevertConflictDetailsSchema = z.object({
+  conflicts: z.array(z.object({ path: z.string(), reason: z.enum(["CHANGED", "UNKNOWN"]) })),
+});
+export type AiRunRevertConflictDetails = z.infer<typeof aiRunRevertConflictDetailsSchema>;
+
+// ─── 실행 이벤트(SSE) ────────────────────────────────────────────────────
+// SSE 한 건 = `id: {seq}` · `event: {type}` · `data: {JSON}`. seq는 실행 안에서 1부터 늘고 끊긴 실행을 이어도 이어진다.
+
+export const aiStreamEventSchema = z.discriminatedUnion("type", [
+  /** 글 조각(약 100ms 묶음). 같은 `messageId`의 `text`에 이어 붙인다 */
+  z.object({ type: z.literal("delta"), messageId: z.string(), text: z.string() }),
+  z.object({
+    type: z.literal("tool_start"),
+    messageId: z.string(),
+    toolCallId: z.string(),
+    name: z.string(),
+    label: z.string(),
+    /** 쓰기 도구가 바꾸는 화면(읽기 도구는 없다) */
+    focus: aiFocusSchema.optional(),
+  }),
+  z.object({
+    type: z.literal("tool_result"),
+    messageId: z.string(),
+    toolCallId: z.string(),
+    status: z.enum(["ok", "error", "unknown"]),
+    summary: z.string().nullable(),
+  }),
+  z.object({
+    type: z.literal("choices"),
+    messageId: z.string(),
+    question: z.string(),
+    options: z.array(z.object({ label: z.string(), value: z.string() })),
+  }),
+  /** 공개 뒤 승인이 필요한 쓰기를 승인 요청으로 남겼다 */
+  z.object({
+    type: z.literal("approval"),
+    messageId: z.string(),
+    approvalId: z.string(),
+    title: z.string(),
+  }),
+  /** 메시지 하나가 확정됐다(이 시점의 내용은 대화 조회와 같다) */
+  z.object({ type: z.literal("message"), message: aiMessageSchema }),
+  z.object({ type: z.literal("error"), code: z.string(), message: z.string() }),
+  /** 실행이 끝났다. 뒤에 이벤트가 없다 */
+  z.object({ type: z.literal("done"), status: aiRunStatusSchema }),
+]);
+export type AiStreamEvent = z.infer<typeof aiStreamEventSchema>;
+
+/** 중계에 쌓이는 이벤트 한 건 — 실행기 → 중계 `POST /internal/streams/{id}/events` */
+export const aiStreamRecordSchema = z.object({
+  seq: z.number().int().positive(),
+  event: aiStreamEventSchema,
+});
+export type AiStreamRecord = z.infer<typeof aiStreamRecordSchema>;
+
+// ─── 웹사이트 초안(#124 M2) ──────────────────────────────────────────────
+
+export const STORE_DRAFT_MAX_ATTACHMENTS = 5;
+/** 초안 첨부 하나의 최대 크기(바이트) */
+export const STORE_DRAFT_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+/** 연결하지 않은 초안을 지우기까지 */
+export const STORE_DRAFT_RETENTION_DAYS = 7;
+
+export const createStoreDraftRequestSchema = z.object({
+  text: z.string().trim().min(1).max(AI_MESSAGE_MAX_CHARS),
+  attachments: z
+    .array(
+      z.object({
+        filename: z.string().trim().min(1).max(200),
+        size: z.number().int().positive().max(STORE_DRAFT_ATTACHMENT_MAX_BYTES),
+      }),
+    )
+    .max(STORE_DRAFT_MAX_ATTACHMENTS)
+    .default([]),
+});
+export type CreateStoreDraftRequest = z.input<typeof createStoreDraftRequestSchema>;
+
+export const createStoreDraftResponseSchema = z.object({
+  draftId: z.string(),
+  /** 첨부마다 브라우저가 파일을 그대로 PUT할 자리(요청 순서와 같다) */
+  uploads: z.array(z.object({ uploadUrl: z.string().url(), url: z.string().url() })),
+  /** 다음 화면 — 상점 플랫폼 `/start?draft=…` */
+  continueUrl: z.string().url(),
+});
+export type CreateStoreDraftResponse = z.infer<typeof createStoreDraftResponseSchema>;
+
+export const storeDraftSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  attachments: z.array(aiAttachmentSchema),
+  createdAt: z.string(),
+  /** 이 초안으로 시작한 상점(없으면 null) */
+  storeId: z.string().nullable(),
+});
+export type StoreDraft = z.infer<typeof storeDraftSchema>;
+
+/** 로그인 전 초안 미리보기(`GET /v1/public/store-drafts/{id}`) — 로그인 화면이 「저장한 설명」을 보인다. 첨부는 이름만 */
+export const storeDraftPreviewSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  attachments: z.array(z.object({ name: z.string(), mediaType: z.string() })),
+  expiresAt: z.string(),
+  /** 이미 상점에서 쓴 초안이면 true(다시 시작할 수 없다) */
+  used: z.boolean(),
+});
+export type StoreDraftPreview = z.infer<typeof storeDraftPreviewSchema>;

package/src/schemas/app-manifest.ts

@@ -8,7 +8,7 @@ import {
 } from "./webhook-event";
 
 /**
- * 서드파티 앱 매니페스트 `sayren.app.json` (이슈 #22) — CLI(`sayren app`)·api(빌드 `VERIFY`·버전 판정·동의 화면 자료)·런타임이
+ * 서드파티 앱 매니페스트 `manifest.json` (이슈 #22) — CLI(`sayren app`)·api(빌드 `VERIFY`·버전 판정·동의 화면 자료)·런타임이
  * 같은 원천을 쓴다. 매니페스트는 정적 JSON이고 빌드 없이 읽는다.
  *
  * 기능 하나는 **capability** 하나다(`APP_CAPABILITIES`). capability는 매니페스트 조각·동의 문단·넓어짐 판정(재동의 조건)을 한 곳에 둔다.

package/src/schemas/apps.ts

@@ -445,7 +445,7 @@ export type DeveloperAppCreate = z.infer<typeof developerAppCreateSchema>;
 
 /** `PUT /platform/v1/developer/apps/{appId}/versions` — CLI `app deploy`가 올리는 번들 */
 export const appArtifactUploadSchema = z.object({
-  manifest: z.unknown().describe("sayren.app.json 원문(JSON)"),
+  manifest: z.unknown().describe("manifest.json 원문(JSON)"),
   packageJson: z.string().max(256 * 1024),
   lockfile: z
     .string()

package/src/schemas/upload.ts

@@ -6,8 +6,14 @@ import { z } from "zod";
  * - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
  * - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
  * - `flow-attachment`: 주문 흐름 행동의 첨부(시안 등, 이슈 #115). 구매자에게 보이므로 정지 이미지와 PDF만 받는다.
+ * - `ai-attachment`: 상점 플랫폼 AI 채팅에 붙이는 자료(이슈 #124). 모델이 읽는 정지 이미지와 PDF만 받는다.
  */
-export const uploadPurposeSchema = z.enum(["product-image", "description", "flow-attachment"]);
+export const uploadPurposeSchema = z.enum([
+  "product-image",
+  "description",
+  "flow-attachment",
+  "ai-attachment",
+]);
 
 export type UploadPurpose = z.infer<typeof uploadPurposeSchema>;
 
@@ -39,6 +45,11 @@ export const UPLOAD_PURPOSE_LIMITS: Record<UploadPurpose, UploadPurposeLimit> =
     extensions: ["jpg", "jpeg", "png", "webp", "avif", "gif", "pdf"],
     maxBytes: 20 * MB,
   },
+  // 모델이 받는 형식(jpeg·png·webp·gif, PDF)만 받는다
+  "ai-attachment": {
+    extensions: ["jpg", "jpeg", "png", "webp", "gif", "pdf"],
+    maxBytes: 10 * MB,
+  },
 };
 
 /** 파일명의 소문자 확장자. 확장자가 없으면 `""` */