@sayren/store-sdk 0.30.12 → 0.30.14

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는 매니페스트 조각·동의 문단·넓어짐 판정(재동의 조건)을 한 곳에 둔다.
@@ -251,6 +251,57 @@ export const APP_SCHEDULE_INTERVALS = {
   "1d": 1440,
 } as const;
 export type AppScheduleInterval = keyof typeof APP_SCHEDULE_INTERVALS;
+
+/** 흐름 알림 이름 — 흐름 알림 채널 `app.<handle>.<이름>`의 마지막 마디(소문자·숫자·하이픈) */
+export const APP_FLOW_NOTIFICATION_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+/** 흐름 사건 이름 — 사건 키 `app.<handle>.<이름>`의 마지막 마디 */
+export const APP_FLOW_EVENT_PATTERN = /^[A-Z][A-Z0-9_]{0,39}$/;
+export const APP_FLOW_ITEMS_MAX = 20;
+
+/** 흐름 알림 매개변수 — 셀러가 편집기에서 식으로 값을 연결한다 */
+export const appFlowParamSchema = z.strictObject({
+  type: z.enum(["string", "number", "boolean"]),
+  label: z.string().trim().min(1).max(60),
+  required: z.boolean().optional(),
+});
+export type AppFlowParam = z.infer<typeof appFlowParamSchema>;
+
+export const appFlowNotificationSchema = z.strictObject({
+  label: z.string().trim().min(1).max(60),
+  description: z.string().trim().max(200).optional(),
+  params: z
+    .record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]{0,39}$/), appFlowParamSchema)
+    .refine((params) => Object.keys(params).length <= APP_FLOW_ITEMS_MAX, {
+      message: `매개변수는 ${APP_FLOW_ITEMS_MAX}개까지입니다`,
+    })
+    .default({}),
+});
+export type AppFlowNotification = z.infer<typeof appFlowNotificationSchema>;
+
+export const appFlowEventSchema = z.strictObject({
+  label: z.string().trim().min(1).max(60),
+  description: z.string().trim().max(200).optional(),
+});
+export type AppFlowEvent = z.infer<typeof appFlowEventSchema>;
+
+/** 에이전트 도구 이름 — 소문자·숫자·하이픈 */
+export const APP_TOOL_NAME_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+export const appToolInputSchema = z.strictObject({
+  type: z.enum(["string", "number", "boolean"]),
+  description: z.string().trim().max(200).optional(),
+  required: z.boolean().optional(),
+});
+export type AppToolInput = z.infer<typeof appToolInputSchema>;
+export const appToolSchema = z.strictObject({
+  description: z.string().trim().min(1).max(500),
+  input: z
+    .record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]{0,39}$/), appToolInputSchema)
+    .refine((input) => Object.keys(input).length <= APP_FLOW_ITEMS_MAX, {
+      message: `입력은 ${APP_FLOW_ITEMS_MAX}개까지입니다`,
+    })
+    .default({}),
+});
+export type AppTool = z.infer<typeof appToolSchema>;
 const APP_SCHEDULE_INTERVAL_KEYS = Object.keys(APP_SCHEDULE_INTERVALS) as [
   AppScheduleInterval,
   ...AppScheduleInterval[],
@@ -306,8 +357,21 @@ export const appManifestSchema = z.strictObject({
     .regex(APP_FOLDER_FILE)
     .refine((path) => /\.md$/i.test(path), { message: "README는 .md 파일입니다" })
     .optional(),
-  /** 실행 위치 — A1은 코드 업로드 앱만. 외부 런타임(`external`)은 A3에서 연다 */
-  runtime: z.literal("code").default("code"),
+  /** 실행 위치 — `code`(sayren이 실행) 또는 `external`(개발자 서버, 매뉴얼 「개발자 서버에서 실행」) */
+  runtime: z.enum(["code", "external"]).default("code"),
+  /** `runtime: external`의 호출 주소 */
+  external: z.strictObject({ url: z.url().startsWith("https://") }).optional(),
+  /** AI 에이전트 도구(매뉴얼 「에이전트 도구」) */
+  mcp: z
+    .strictObject({
+      tools: z
+        .record(z.string().regex(APP_TOOL_NAME_PATTERN), appToolSchema)
+        .refine((tools) => Object.keys(tools).length <= APP_FLOW_ITEMS_MAX, {
+          message: `도구는 ${APP_FLOW_ITEMS_MAX}개까지입니다`,
+        })
+        .default({}),
+    })
+    .optional(),
   /** 설치 때 전체 동의하는 스코프 */
   scopes: z.array(appScopeSchema).max(32).default([]),
   network: z
@@ -337,6 +401,23 @@ export const appManifestSchema = z.strictObject({
       message: `예약 작업은 ${APP_SCHEDULES_MAX}개까지입니다`,
     })
     .default({}),
+  /** 주문 흐름 연동(매뉴얼 「주문 흐름에서 앱 쓰기」) — 흐름 알림(흐름 → 앱)과 흐름 사건(앱 → 흐름) */
+  flow: z
+    .strictObject({
+      notifications: z
+        .record(z.string().regex(APP_FLOW_NOTIFICATION_PATTERN), appFlowNotificationSchema)
+        .refine((items) => Object.keys(items).length <= APP_FLOW_ITEMS_MAX, {
+          message: `흐름 알림은 ${APP_FLOW_ITEMS_MAX}개까지입니다`,
+        })
+        .default({}),
+      events: z
+        .record(z.string().regex(APP_FLOW_EVENT_PATTERN), appFlowEventSchema)
+        .refine((items) => Object.keys(items).length <= APP_FLOW_ITEMS_MAX, {
+          message: `흐름 사건은 ${APP_FLOW_ITEMS_MAX}개까지입니다`,
+        })
+        .default({}),
+    })
+    .optional(),
   settings: z
     .record(z.string().regex(APP_SETTING_KEY_PATTERN), appSettingFieldSchema)
     .refine((fields) => Object.keys(fields).length <= APP_SETTINGS_MAX_FIELDS, {
@@ -369,7 +450,10 @@ export interface AppManifestProblem {
     | "SELECT_OPTIONS_REQUIRED"
     | "SECRET_FIELD_TYPE"
     | "DEFAULT_TYPE_MISMATCH"
-    | "DUPLICATE";
+    | "DUPLICATE"
+    | "EXTERNAL_URL_REQUIRED"
+    | "EXTERNAL_NETWORK_HOSTS"
+    | "EXTERNAL_URL_INVALID";
   message: string;
 }
 
@@ -390,6 +474,28 @@ export function appManifestProblems(manifest: AppManifest): AppManifestProblem[]
   unique(manifest.network.hosts, "network.hosts", "호스트");
   unique(manifest.secrets, "secrets", "비밀 값 이름");
   unique(manifest.http?.public ?? [], "http.public", "공개 HTTP 핸들러");
+  // 외부 런타임 — 주소가 있어야 하고, 내보내는 곳을 sayren이 막을 수 없어 network.hosts를 받지 않는다
+  if ((manifest.runtime === "external") !== Boolean(manifest.external)) {
+    problems.push({
+      path: "external",
+      code: "EXTERNAL_URL_REQUIRED",
+      message: "runtime이 external이면 external.url이 필요하고, code면 external을 적지 않습니다",
+    });
+  }
+  if (manifest.runtime === "external" && manifest.network.hosts.length > 0) {
+    problems.push({
+      path: "network.hosts",
+      code: "EXTERNAL_NETWORK_HOSTS",
+      message: "외부 런타임 앱은 network.hosts를 적지 않습니다",
+    });
+  }
+  if (manifest.external) {
+    const host = new URL(manifest.external.url).hostname;
+    const hostProblem = appNetworkHostProblem(host);
+    if (hostProblem) {
+      problems.push({ path: "external.url", code: "EXTERNAL_URL_INVALID", message: hostProblem });
+    }
+  }
   for (const event of manifest.events) {
     if (!scopesCoverEvent(manifest.scopes, event)) {
       problems.push({
@@ -442,6 +548,13 @@ export interface AppCapabilities {
   publicHttp?: string[];
   /** 예약 작업 이름 → 간격. 옛 버전 행에는 없다 — 읽을 때 `?? {}` */
   schedules?: Record<string, AppScheduleInterval>;
+  /** 흐름 알림(이름 → 표시 이름·매개변수)·흐름 사건(이름 → 표시 이름). 옛 버전 행에는 없다 — 읽을 때 `?? {}` */
+  flowNotifications?: Record<string, AppFlowNotification>;
+  flowEvents?: Record<string, AppFlowEvent>;
+  /** 외부 런타임의 호출 호스트(동의 화면). 코드 앱·옛 버전 행은 없다 */
+  externalHost?: string | null;
+  /** 에이전트 도구. 옛 버전 행에는 없다 — 읽을 때 `?? {}` */
+  tools?: Record<string, AppTool>;
   /** 필수 설정 키 — 하나라도 비어 있으면 이벤트 함수를 부르지 않는다 */
   requiredSettings: string[];
   secretSettings: string[];
@@ -455,6 +568,10 @@ export function appCapabilitiesOf(manifest: AppManifest): AppCapabilities {
     networkHosts: sorted(manifest.network.hosts),
     adminPage: Boolean(manifest.ui?.adminPage),
     publicHttp: sorted(manifest.http?.public ?? []),
+    flowNotifications: manifest.flow?.notifications ?? {},
+    flowEvents: manifest.flow?.events ?? {},
+    externalHost: manifest.external ? new URL(manifest.external.url).hostname : null,
+    tools: manifest.mcp?.tools ?? {},
     schedules: Object.fromEntries(
       Object.entries(manifest.schedules)
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
@@ -476,7 +593,7 @@ export function appCapabilitiesOf(manifest: AppManifest): AppCapabilities {
  * 동의 문단은 accounts 설치 화면·상점 플랫폼 앱 상세·유저 문서가 같은 문장을 쓴다.
  */
 export interface AppCapabilityDefinition {
-  key: "scopes" | "network" | "events" | "ui" | "publicHttp" | "schedules";
+  key: "scopes" | "network" | "events" | "ui" | "publicHttp" | "schedules" | "runtime" | "tools";
   /** 동의 화면의 문단 제목 */
   title: string;
   /** 동의 화면에 보일 줄 — 없으면 문단을 그리지 않는다 */
@@ -545,6 +662,19 @@ export const APP_CAPABILITIES: readonly AppCapabilityDefinition[] = [
       );
     },
   },
+  {
+    key: "runtime",
+    title: "이 앱이 실행되는 곳",
+    describe: (c) => (c.externalHost ? [`개발자 서버 ${c.externalHost}`] : []),
+    widens: (p, n) => Boolean(n.externalHost) && n.externalHost !== p.externalHost,
+  },
+  {
+    key: "tools",
+    title: "AI 에이전트 도구",
+    describe: (c) =>
+      Object.entries(c.tools ?? {}).map(([name, tool]) => `${name} · ${tool.description}`),
+    widens: (p, n) => grew(Object.keys(p.tools ?? {}), Object.keys(n.tools ?? {})),
+  },
 ];
 
 /** 요청(메서드·경로)이 HTTP 핸들러 키에 맞는가 — `:이름`은 경로 한 마디에 맞는다(`@sayren/app`의 핸들러 고르기와 같은 규칙) */
@@ -567,6 +697,48 @@ export function appScheduleListOf(
     .map(([name, every]) => ({ name, every }));
 }
 
+/** 응답용 흐름 알림·사건 목록(이름순) — 옛 버전 행은 빈 목록 */
+export function appFlowSummaryOf(
+  capabilities: Pick<AppCapabilities, "flowNotifications" | "flowEvents">,
+): {
+  flowNotifications: Array<{
+    name: string;
+    label: string;
+    params: Array<{ name: string; type: AppFlowParam["type"]; label: string; required: boolean }>;
+  }>;
+  flowEvents: Array<{ name: string; label: string }>;
+} {
+  const byName = <T>(entries: [string, T][]) =>
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return {
+    flowNotifications: byName(Object.entries(capabilities.flowNotifications ?? {})).map(
+      ([name, notice]) => ({
+        name,
+        label: notice.label,
+        params: byName(Object.entries(notice.params ?? {})).map(([param, field]) => ({
+          name: param,
+          type: field.type,
+          label: field.label,
+          required: field.required ?? false,
+        })),
+      }),
+    ),
+    flowEvents: byName(Object.entries(capabilities.flowEvents ?? {})).map(([name, event]) => ({
+      name,
+      label: event.label,
+    })),
+  };
+}
+
+/** 응답용 도구 목록(이름순) — 옛 버전 행은 빈 목록 */
+export function appToolListOf(
+  capabilities: Pick<AppCapabilities, "tools">,
+): Array<{ name: string; description: string }> {
+  return Object.entries(capabilities.tools ?? {})
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([name, tool]) => ({ name, description: tool.description }));
+}
+
 /** 예약 간격의 표시 이름 — 동의 화면·상점 플랫폼이 같이 쓴다 */
 export function appScheduleIntervalLabel(every: AppScheduleInterval): string {
   const minutes = APP_SCHEDULE_INTERVALS[every];

package/src/schemas/apps.ts

@@ -76,11 +76,38 @@ const publicHttpField = z
   .array(z.string())
   .default([])
   .describe("외부에서 부를 수 있는 HTTP 핸들러(`GET /track/:id`)");
+/** 흐름 알림·사건(매뉴얼 「주문 흐름에서 앱 쓰기」) — 흐름 편집기가 알림 채널·매개변수와 사건 이름을 고른다 */
+export const appFlowNotificationSummarySchema = z.object({
+  name: z.string(),
+  label: z.string(),
+  params: z.array(
+    z.object({
+      name: z.string(),
+      type: z.enum(["string", "number", "boolean"]),
+      label: z.string(),
+      required: z.boolean(),
+    }),
+  ),
+});
+export type AppFlowNotificationSummary = z.infer<typeof appFlowNotificationSummarySchema>;
+export const appFlowEventSummarySchema = z.object({ name: z.string(), label: z.string() });
+export type AppFlowEventSummary = z.infer<typeof appFlowEventSummarySchema>;
+
 const schedulesField = z
   .array(appScheduleSummarySchema)
   .default([])
   .describe("주기적으로 실행되는 작업");
 
+const toolsField = z
+  .array(z.object({ name: z.string(), description: z.string() }))
+  .default([])
+  .describe("AI 에이전트 도구");
+const externalHostField = z
+  .string()
+  .nullable()
+  .default(null)
+  .describe("개발자 서버에서 실행하는 앱의 호출 호스트. sayren이 실행하면 null");
+
 export const appInstallationSchema = z.object({
   installationId: z.string(),
   storeId: z.string(),
@@ -100,6 +127,8 @@ export const appInstallationSchema = z.object({
       events: z.array(appEventTypeSchema),
       publicHttp: publicHttpField,
       schedules: schedulesField,
+      tools: toolsField,
+      externalHost: externalHostField,
     })
     .nullable()
     .optional()
@@ -110,6 +139,16 @@ export const appInstallationSchema = z.object({
   adminPage: z.boolean().describe("상점 플랫폼 앱 화면이 있는가"),
   publicHttp: publicHttpField,
   schedules: schedulesField,
+  tools: toolsField,
+  externalHost: externalHostField,
+  flowNotifications: z
+    .array(appFlowNotificationSummarySchema)
+    .default([])
+    .describe("주문 흐름에서 이 앱으로 보낼 수 있는 알림"),
+  flowEvents: z
+    .array(appFlowEventSummarySchema)
+    .default([])
+    .describe("이 앱이 주문 흐름에 보내는 사건(`app.<handle>.<이름>`)"),
   /** 설치 결과의 캐시가 아니라 실행 버전 매니페스트의 요약 */
   settings: appInstallationSettingsSchema,
   installedBy: z.object({ userId: z.string(), name: z.string().nullable() }).nullable(),
@@ -197,6 +236,8 @@ export const storeAppDetailSchema = storeAppSchema.extend({
   networkHosts: z.array(z.string()).describe("앱이 데이터를 보내는 외부 호스트"),
   publicHttp: publicHttpField,
   schedules: schedulesField,
+  tools: toolsField,
+  externalHost: externalHostField,
   settings: z.record(z.string(), appSettingFieldSchema).describe("설치 때 채우는 설정 필드"),
   updatedAt: z.string().nullable().describe("현재 버전을 release한 시각"),
 });
@@ -222,6 +263,33 @@ export const appInstallationSelfSchema = z.object({
 });
 export type AppInstallationSelf = z.infer<typeof appInstallationSelfSchema>;
 
+/** 에이전트 도구(매뉴얼 「에이전트 도구」) — `GET /v1/apps/tools` 한 줄 */
+export const appToolSummarySchema = z.object({
+  installationId: z.string(),
+  app: z.object({ appId: z.string(), handle: z.string(), name: z.string() }),
+  name: z.string(),
+  description: z.string(),
+  input: z.array(
+    z.object({
+      name: z.string(),
+      type: z.enum(["string", "number", "boolean"]),
+      description: z.string().nullable(),
+      required: z.boolean(),
+    }),
+  ),
+});
+export type AppToolSummary = z.infer<typeof appToolSummarySchema>;
+
+export const appToolCallSchema = z.object({
+  input: z.record(z.string(), z.unknown()).default({}),
+});
+export type AppToolCall = z.input<typeof appToolCallSchema>;
+
+export const appToolResultSchema = z.object({
+  result: z.unknown().describe("앱 도구가 돌려준 값(JSON)"),
+});
+export type AppToolResult = z.infer<typeof appToolResultSchema>;
+
 /** 설치 저장소(`ctx.storage`, 매뉴얼 「앱 코드 › 저장소」) — 설치 토큰 전용 */
 export const APP_STORAGE_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,200}$/;
 export const APP_STORAGE_MAX_KEYS = 1_000;
@@ -377,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()
@@ -464,7 +532,7 @@ export const appInvocationSchema = z.object({
   storeName: z.string().nullable(),
   installationId: z.string(),
   versionNumber: z.number().int().nullable(),
-  kind: z.enum(["event", "http", "schedule"]),
+  kind: z.enum(["event", "http", "schedule", "flow", "tool"]),
   eventType: z.string().nullable(),
   outcome: z.enum(["OK", "ERROR", "LIMIT_EXCEEDED", "REJECTED"]),
   errorMessage: z.string().nullable(),

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,
+  },
 };
 
 /** 파일명의 소문자 확장자. 확장자가 없으면 `""` */