@sayren/store-sdk 0.30.11 → 0.30.13

package/src/schemas/app-manifest.ts

@@ -233,6 +233,79 @@ export const APP_SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
 export const APP_SECRETS_MAX = 20;
 export const APP_EVENTS_MAX = 50;
 export const APP_NETWORK_HOSTS_MAX = 20;
+export const APP_PUBLIC_HTTP_MAX = 20;
+export const APP_SCHEDULES_MAX = 10;
+
+/** HTTP 핸들러 키 — `"<메서드> <경로>"`(`@sayren/app` `defineApp({ http })`와 같은 형식) */
+export const APP_HTTP_KEY_PATTERN = /^(GET|POST|PUT|PATCH|DELETE) (\/[A-Za-z0-9._~:/-]*)$/;
+/** 예약 작업 이름 — 설정 키와 같은 형식 */
+export const APP_SCHEDULE_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{0,39}$/;
+/** 예약 작업 간격 → 분 */
+export const APP_SCHEDULE_INTERVALS = {
+  "15m": 15,
+  "30m": 30,
+  "1h": 60,
+  "3h": 180,
+  "6h": 360,
+  "12h": 720,
+  "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[],
+];
 
 /** 앱 목록에 보이는 아이콘·README(#22 앱 목록 시안) — 앱 폴더의 파일을 `sayren app deploy`가 버전과 함께 올린다 */
 export const APP_ICON_MAX_BYTES = 256 * 1024;
@@ -284,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
@@ -299,6 +385,39 @@ export const appManifestSchema = z.strictObject({
       adminPage: z.strictObject({ entry: z.string().regex(/^ui\/[A-Za-z0-9._/-]+\.html$/) }),
     })
     .optional(),
+  /** 공개 HTTP — 여기 적은 핸들러만 `https://{handle}.{앱 도메인}/hooks/{설치 id}/…`로 외부에서 부를 수 있다 */
+  http: z
+    .strictObject({
+      public: z.array(z.string().regex(APP_HTTP_KEY_PATTERN)).max(APP_PUBLIC_HTTP_MAX),
+    })
+    .optional(),
+  /** 예약 작업 — 이름마다 실행 간격 */
+  schedules: z
+    .record(
+      z.string().regex(APP_SCHEDULE_NAME_PATTERN),
+      z.strictObject({ every: z.enum(APP_SCHEDULE_INTERVAL_KEYS) }),
+    )
+    .refine((schedules) => Object.keys(schedules).length <= APP_SCHEDULES_MAX, {
+      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, {
@@ -331,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;
 }
 
@@ -351,6 +473,29 @@ export function appManifestProblems(manifest: AppManifest): AppManifestProblem[]
   unique(manifest.events, "events", "이벤트");
   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({
@@ -399,6 +544,17 @@ export interface AppCapabilities {
   events: AppEventType[];
   networkHosts: string[];
   adminPage: boolean;
+  /** 공개 HTTP 핸들러 키(`"GET /track/:id"`). 옛 버전 행에는 없다 — 읽을 때 `?? []` */
+  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[];
@@ -411,6 +567,16 @@ export function appCapabilitiesOf(manifest: AppManifest): AppCapabilities {
     events: sorted(manifest.events) as AppEventType[],
     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))
+        .map(([name, schedule]) => [name, schedule.every]),
+    ),
     requiredSettings: Object.entries(manifest.settings)
       .filter(([, field]) => field.required)
       .map(([key]) => key)
@@ -427,7 +593,7 @@ export function appCapabilitiesOf(manifest: AppManifest): AppCapabilities {
  * 동의 문단은 accounts 설치 화면·상점 플랫폼 앱 상세·유저 문서가 같은 문장을 쓴다.
  */
 export interface AppCapabilityDefinition {
-  key: "scopes" | "network" | "events" | "ui";
+  key: "scopes" | "network" | "events" | "ui" | "publicHttp" | "schedules" | "runtime" | "tools";
   /** 동의 화면의 문단 제목 */
   title: string;
   /** 동의 화면에 보일 줄 — 없으면 문단을 그리지 않는다 */
@@ -473,8 +639,114 @@ export const APP_CAPABILITIES: readonly AppCapabilityDefinition[] = [
     describe: (c) => (c.adminPage ? ["상점 플랫폼에 이 앱의 화면을 더합니다"] : []),
     widens: (p, n) => !p.adminPage && n.adminPage,
   },
+  {
+    key: "publicHttp",
+    title: "외부에서 이 앱을 부르는 주소",
+    describe: (c) => c.publicHttp ?? [],
+    widens: (p, n) => grew(p.publicHttp ?? [], n.publicHttp ?? []),
+  },
+  {
+    key: "schedules",
+    title: "주기적으로 실행되는 작업",
+    describe: (c) =>
+      Object.entries(c.schedules ?? {}).map(
+        ([name, every]) => `${name} · ${appScheduleIntervalLabel(every)}마다`,
+      ),
+    widens: (p, n) => {
+      const previous = p.schedules ?? {};
+      return Object.entries(n.schedules ?? {}).some(
+        ([name, every]) =>
+          !previous[name] ||
+          APP_SCHEDULE_INTERVALS[every] <
+            APP_SCHEDULE_INTERVALS[previous[name] as AppScheduleInterval],
+      );
+    },
+  },
+  {
+    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`의 핸들러 고르기와 같은 규칙) */
+export function appHttpKeyMatches(key: string, method: string, path: string): boolean {
+  const match = APP_HTTP_KEY_PATTERN.exec(key.trim().replace(/\s+/g, " "));
+  if (!match || match[1] !== method.toUpperCase()) return false;
+  const pattern = (match[2] as string).split("/");
+  const actual = (path.split("?")[0] ?? path).split("/");
+  if (pattern.length !== actual.length) return false;
+  return pattern.every((part, i) => (part.startsWith(":") ? actual[i] !== "" : part === actual[i]));
+}
+
+/** 응답용 예약 작업 목록(이름순) — 옛 버전 행(`schedules` 없음)은 빈 목록 */
+export function appScheduleListOf(
+  capabilities: Pick<AppCapabilities, "schedules">,
+): Array<{ name: string; every: AppScheduleInterval }> {
+  // jsonb는 키를 길이순으로 저장한다 — 이름순으로 맞춘다
+  return Object.entries(capabilities.schedules ?? {})
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .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];
+  if (minutes < 60) return `${minutes}분`;
+  if (minutes < 1440) return `${minutes / 60}시간`;
+  return "하루";
+}
+
 /** 재동의가 필요한 capability 키 — 비어 있으면 release가 모든 설치에 곧바로 반영된다 */
 export function appManifestWidens(
   previous: AppCapabilities,

package/src/schemas/apps.ts

@@ -29,6 +29,10 @@ export const appInstallationStatusSchema = z.enum(["ACTIVE", "UNINSTALLED", "SUS
 export type AppInstallationStatus = z.infer<typeof appInstallationStatusSchema>;
 
 /** 설치 앱의 앱 정보 — 상점이 보는 범위만(개발자 비밀 값·소스·빌드는 없다) */
+/** 상점이 보는 앱 공개 범위 — 개발 중(개발자 조직) · 이 상점 전용 · 공개 */
+export const appVisibilitySchema = z.enum(["DEVELOPMENT", "PRIVATE", "PUBLIC"]);
+export type AppVisibility = z.infer<typeof appVisibilitySchema>;
+
 export const appInstallationAppSchema = z.object({
   appId: z.string(),
   handle: z.string().describe("앱 handle. 앱 화면 주소의 라벨"),
@@ -61,6 +65,49 @@ export const appInstallationSettingsUpdateSchema = z.object({
 });
 export type AppInstallationSettingsUpdate = z.infer<typeof appInstallationSettingsUpdateSchema>;
 
+/** 예약 작업 한 줄 — 매니페스트 `schedules`의 이름과 간격 */
+export const appScheduleSummarySchema = z.object({
+  name: z.string(),
+  every: z.enum(["15m", "30m", "1h", "3h", "6h", "12h", "1d"]),
+});
+export type AppScheduleSummary = z.infer<typeof appScheduleSummarySchema>;
+
+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(),
@@ -78,6 +125,10 @@ export const appInstallationSchema = z.object({
       scopes: z.array(z.string()),
       networkHosts: z.array(z.string()),
       events: z.array(appEventTypeSchema),
+      publicHttp: publicHttpField,
+      schedules: schedulesField,
+      tools: toolsField,
+      externalHost: externalHostField,
     })
     .nullable()
     .optional()
@@ -86,6 +137,18 @@ export const appInstallationSchema = z.object({
   grantedNetworkHosts: z.array(z.string()).describe("동의한 외부 호출 호스트"),
   events: z.array(appEventTypeSchema).describe("이 설치가 받는 이벤트"),
   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(),
@@ -158,6 +221,9 @@ export const storeAppSchema = z.object({
   developerName: z.string(),
   versionNumber: z.number().int().describe("현재 버전"),
   installationId: z.string().nullable().describe("이 상점에 설치돼 있으면 설치 id"),
+  visibility: appVisibilitySchema
+    .default("DEVELOPMENT")
+    .describe("공개 범위 — 개발 중(심사 전) · 이 상점 전용 · 공개(심사 통과)"),
 });
 export type StoreApp = z.infer<typeof storeAppSchema>;
 
@@ -168,6 +234,10 @@ export const storeAppDetailSchema = storeAppSchema.extend({
   scopes: z.array(z.string()).describe("설치 때 동의하는 스코프(Scope)"),
   events: z.array(appEventTypeSchema).describe("받는 이벤트(Hook)"),
   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한 시각"),
 });
@@ -193,6 +263,60 @@ 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;
+/** 설치당 전체 크기(키 + JSON 값, UTF-8 바이트) */
+export const APP_STORAGE_MAX_BYTES = 1024 * 1024;
+
+export const appStorageEntrySchema = z.object({
+  key: z.string(),
+  value: z.unknown().describe("저장한 JSON 값"),
+  updatedAt: z.string(),
+});
+export type AppStorageEntry = z.infer<typeof appStorageEntrySchema>;
+
+export const appStorageKeysSchema = z.object({
+  keys: z.array(z.string()).describe("키 목록(이름순)"),
+});
+export type AppStorageKeys = z.infer<typeof appStorageKeysSchema>;
+
+export const appStoragePutSchema = z.object({
+  value: z.unknown().refine((value) => value !== undefined, { message: "value가 필요합니다" }),
+});
+export type AppStoragePut = z.infer<typeof appStoragePutSchema>;
+
+export const appStorageListQuerySchema = z.object({
+  prefix: z.string().max(200).optional(),
+});
+
 export type { AppCapabilities };
 
 // ─── 개발자 API (플랫폼 플레인 `/platform/v1/developer/**`, 공개 문서 제외 — CLI·상점 플랫폼 개발자 화면이 쓴다) ───
@@ -249,6 +373,8 @@ export const appVersionSchema = z.object({
     events: z.array(z.string()),
     networkHosts: z.array(z.string()),
     adminPage: z.boolean(),
+    publicHttp: z.array(z.string()).optional(),
+    schedules: z.record(z.string(), z.string()).optional(),
     requiredSettings: z.array(z.string()),
     secretSettings: z.array(z.string()),
   }),
@@ -264,6 +390,19 @@ export const appVersionSchema = z.object({
 });
 export type AppVersion = z.infer<typeof appVersionSchema>;
 
+/** 앱 공개 심사(#22, 매뉴얼 「앱 공개 범위」) — 개발자가 신청하고 운영자가 승인·반려한다 */
+export const appListingReviewStatusSchema = z.enum(["PENDING", "APPROVED", "REJECTED"]);
+export type AppListingReviewStatus = z.infer<typeof appListingReviewStatusSchema>;
+export const appListingReviewSchema = z.object({
+  reviewId: z.string(),
+  status: appListingReviewStatusSchema,
+  versionNumber: z.number().int().describe("신청 때 현재 버전"),
+  reason: z.string().nullable().describe("반려 사유"),
+  requestedAt: z.string(),
+  reviewedAt: z.string().nullable(),
+});
+export type AppListingReview = z.infer<typeof appListingReviewSchema>;
+
 export const developerAppSchema = z.object({
   appId: z.string(),
   orgId: z.string(),
@@ -277,6 +416,15 @@ export const developerAppSchema = z.object({
   status: appStatusSchema,
   suspendedReason: z.string().nullable(),
   currentVersionNumber: z.number().int().nullable(),
+  privateStoreId: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe("비공개 앱이 묶인 상점. 개발 중·퍼블릭 앱은 null"),
+  listingReview: appListingReviewSchema
+    .nullable()
+    .default(null)
+    .describe("마지막 공개 신청. 없으면 null"),
   installations: z.object({
     active: z.number().int(),
     pendingReconsent: z.number().int(),
@@ -290,6 +438,8 @@ export const developerAppCreateSchema = z.object({
   handle: appHandleSchema,
   name: z.string().trim().min(1).max(60),
   description: z.string().trim().max(500).optional(),
+  /** 비공개 앱 — 이 상점 하나에만 설치된다. 만드는 사람이 그 상점의 OWNER·ADMIN이어야 한다 */
+  privateStoreId: z.string().min(1).optional(),
 });
 export type DeveloperAppCreate = z.infer<typeof developerAppCreateSchema>;
 
@@ -345,6 +495,15 @@ export const devStoreSchema = z.object({
 });
 export type DevStore = z.infer<typeof devStoreSchema>;
 
+/** `GET /platform/v1/developer/stores` — 비공개 앱을 묶을 수 있는 상점(내가 소유자·관리자, 운영 중) */
+export const developerStoreSchema = z.object({
+  storeId: z.string(),
+  name: z.string(),
+  role: z.enum(["OWNER", "ADMIN"]),
+  development: z.boolean().describe("개발 상점인가"),
+});
+export type DeveloperStore = z.infer<typeof developerStoreSchema>;
+
 /** 개발자가 보는 설치 한 줄 */
 export const developerInstallationSchema = z.object({
   installationId: z.string(),
@@ -373,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(),