@sayren/store-sdk 0.30.10 → 0.30.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.30.10",
+  "version": "0.30.12",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -23,11 +23,14 @@ import {
 import { type ApiLogListOptions, apiLogPageSchema, apiLogSummarySchema } from "./schemas/api-log";
 import {
   type AppInstallationSettingsUpdate,
+  appInstallationActivitySchema,
   appInstallationSchema,
   appInstallationSelfSchema,
   appInstallationSettingsUpdateSchema,
   appInstallRequestSchema,
   appSessionSchema,
+  appStorageEntrySchema,
+  appStorageKeysSchema,
   storeAppDetailSchema,
   storeAppSchema,
 } from "./schemas/apps";
@@ -1469,6 +1472,20 @@ export function createStoreClient(options: StoreClientOptions) {
           ),
         remove: (installationId: string) =>
           storeHttp.requestVoid("DELETE", path`/apps/installations/${installationId}`),
+        /** 실행 기록 — 최근 이벤트 전송 결과와 최근 7일 관리 API 호출 수 */
+        activity: (installationId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/apps/installations/${installationId}/activity`,
+            appInstallationActivitySchema,
+          ),
+        /** 권한 업데이트 동의 — 넓어진 새 버전(`pendingVersion`)으로 옮긴다(상점 플랫폼 전용) */
+        consent: (installationId: string) =>
+          storeHttp.request(
+            "POST",
+            path`/apps/installations/${installationId}/consent`,
+            appInstallationSchema,
+          ),
         /** 앱 화면 iframe에 넘길 세션 토큰(5분) */
         session: (installationId: string) =>
           storeHttp.request(
@@ -1481,6 +1498,20 @@ export function createStoreClient(options: StoreClientOptions) {
     /** 앱 설치 토큰 전용 — 자기 설치 */
     app: {
       installation: () => storeHttp.request("GET", "/app/installation", appInstallationSelfSchema),
+      /** 설치 저장소(`ctx.storage`) — 없는 키는 404 `APP_STORAGE_KEY_NOT_FOUND`, 한도 초과는 409 `APP_STORAGE_LIMIT` */
+      storage: {
+        list: (params: { prefix?: string } = {}) =>
+          storeHttp.request("GET", "/app/storage", appStorageKeysSchema, {
+            query: params as unknown as Query,
+          }),
+        get: (key: string) =>
+          storeHttp.request("GET", path`/app/storage/${key}`, appStorageEntrySchema),
+        set: (key: string, value: unknown) =>
+          storeHttp.request("PUT", path`/app/storage/${key}`, appStorageEntrySchema, {
+            body: { value },
+          }),
+        delete: (key: string) => storeHttp.requestVoid("DELETE", path`/app/storage/${key}`),
+      },
     },
 
     webhooks: {

package/src/schemas/app-manifest.ts

@@ -233,6 +233,28 @@ 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;
+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;
@@ -299,6 +321,22 @@ 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({}),
   settings: z
     .record(z.string().regex(APP_SETTING_KEY_PATTERN), appSettingFieldSchema)
     .refine((fields) => Object.keys(fields).length <= APP_SETTINGS_MAX_FIELDS, {
@@ -351,6 +389,7 @@ 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 핸들러");
   for (const event of manifest.events) {
     if (!scopesCoverEvent(manifest.scopes, event)) {
       problems.push({
@@ -399,6 +438,10 @@ export interface AppCapabilities {
   events: AppEventType[];
   networkHosts: string[];
   adminPage: boolean;
+  /** 공개 HTTP 핸들러 키(`"GET /track/:id"`). 옛 버전 행에는 없다 — 읽을 때 `?? []` */
+  publicHttp?: string[];
+  /** 예약 작업 이름 → 간격. 옛 버전 행에는 없다 — 읽을 때 `?? {}` */
+  schedules?: Record<string, AppScheduleInterval>;
   /** 필수 설정 키 — 하나라도 비어 있으면 이벤트 함수를 부르지 않는다 */
   requiredSettings: string[];
   secretSettings: string[];
@@ -411,6 +454,12 @@ 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 ?? []),
+    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 +476,7 @@ export function appCapabilitiesOf(manifest: AppManifest): AppCapabilities {
  * 동의 문단은 accounts 설치 화면·상점 플랫폼 앱 상세·유저 문서가 같은 문장을 쓴다.
  */
 export interface AppCapabilityDefinition {
-  key: "scopes" | "network" | "events" | "ui";
+  key: "scopes" | "network" | "events" | "ui" | "publicHttp" | "schedules";
   /** 동의 화면의 문단 제목 */
   title: string;
   /** 동의 화면에 보일 줄 — 없으면 문단을 그리지 않는다 */
@@ -473,8 +522,59 @@ 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],
+      );
+    },
+  },
 ];
 
+/** 요청(메서드·경로)이 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 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

@@ -7,6 +7,7 @@ import {
   appHandleSchema,
   appSettingFieldSchema,
 } from "./app-manifest";
+import { webhookDeliveryErrorCodeSchema, webhookDeliveryStatusSchema } from "./misc";
 
 /**
  * 설치 앱 관리 API 계약 (이슈 #22) — `/v1/apps/installations/**`(상점이 설치한 앱), `/v1/app/installation`(설치 토큰 자기 조회).
@@ -28,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. 앱 화면 주소의 라벨"),
@@ -60,6 +65,22 @@ 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`)");
+const schedulesField = z
+  .array(appScheduleSummarySchema)
+  .default([])
+  .describe("주기적으로 실행되는 작업");
+
 export const appInstallationSchema = z.object({
   installationId: z.string(),
   storeId: z.string(),
@@ -71,10 +92,24 @@ export const appInstallationSchema = z.object({
     .int()
     .nullable()
     .describe("재동의가 필요한 새 버전. 없으면 null"),
+  pendingVersion: z
+    .object({
+      number: z.number().int(),
+      scopes: z.array(z.string()),
+      networkHosts: z.array(z.string()),
+      events: z.array(appEventTypeSchema),
+      publicHttp: publicHttpField,
+      schedules: schedulesField,
+    })
+    .nullable()
+    .optional()
+    .describe("재동의가 필요한 새 버전이 요청하는 권한·외부 호스트·이벤트(전체). 없으면 null"),
   grantedScopes: z.array(z.string()).describe("동의한 스코프"),
   grantedNetworkHosts: z.array(z.string()).describe("동의한 외부 호출 호스트"),
   events: z.array(appEventTypeSchema).describe("이 설치가 받는 이벤트"),
   adminPage: z.boolean().describe("상점 플랫폼 앱 화면이 있는가"),
+  publicHttp: publicHttpField,
+  schedules: schedulesField,
   /** 설치 결과의 캐시가 아니라 실행 버전 매니페스트의 요약 */
   settings: appInstallationSettingsSchema,
   installedBy: z.object({ userId: z.string(), name: z.string().nullable() }).nullable(),
@@ -84,6 +119,26 @@ export const appInstallationSchema = z.object({
 });
 export type AppInstallation = z.infer<typeof appInstallationSchema>;
 
+/** 실행 기록 한 줄 — 앱에 보낸 이벤트 하나의 전송 결과. 로그 본문은 개발자만 본다(매뉴얼 「앱 설치와 관리」) */
+export const appInstallationRunSchema = z.object({
+  deliveryId: z.string(),
+  eventType: z.string().describe("이벤트 이름(`ORDER.PAID`·`APP.INSTALLED` 등)"),
+  status: webhookDeliveryStatusSchema,
+  errorCode: webhookDeliveryErrorCodeSchema.nullable(),
+  attemptCount: z.number().int(),
+  createdAt: z.string(),
+  attemptedAt: z.string().nullable(),
+  nextAttemptAt: z.string().nullable(),
+});
+export type AppInstallationRun = z.infer<typeof appInstallationRunSchema>;
+
+/** `GET /v1/apps/installations/{id}/activity` — 최근 이벤트 전송 결과(50건)와 최근 7일 관리 API 호출 수 */
+export const appInstallationActivitySchema = z.object({
+  runs: z.array(appInstallationRunSchema),
+  apiCalls7d: z.number().int().describe("최근 7일 이 설치가 부른 관리 API 수"),
+});
+export type AppInstallationActivity = z.infer<typeof appInstallationActivitySchema>;
+
 /**
  * `POST /v1/apps/installations`(상점 플랫폼 전용) — 둘 중 하나다.
  * - `{ result }`: accounts 설치 동의 결과(1회용 JWT). 개발자 포털 [내 상점에 설치]가 이 길로 온다
@@ -127,6 +182,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>;
 
@@ -137,6 +195,8 @@ 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,
   settings: z.record(z.string(), appSettingFieldSchema).describe("설치 때 채우는 설정 필드"),
   updatedAt: z.string().nullable().describe("현재 버전을 release한 시각"),
 });
@@ -162,6 +222,33 @@ export const appInstallationSelfSchema = z.object({
 });
 export type AppInstallationSelf = z.infer<typeof appInstallationSelfSchema>;
 
+/** 설치 저장소(`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·상점 플랫폼 개발자 화면이 쓴다) ───
@@ -218,6 +305,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()),
   }),
@@ -233,6 +322,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(),
@@ -246,6 +348,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(),
@@ -259,6 +370,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>;
 
@@ -314,6 +427,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(),