@sayren/store-sdk 0.30.9 → 0.30.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.30.9",
+  "version": "0.30.11",
   "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,
+  storeAppDetailSchema,
+  storeAppSchema,
 } from "./schemas/apps";
 import {
   type ApprovalDecisionRequest,
@@ -1432,11 +1435,23 @@ export function createStoreClient(options: StoreClientOptions) {
 
     /** 설치 앱(#22, 매뉴얼 「앱 설치와 관리 › 관리 API」) — 설치·설정·제거·세션은 상점 플랫폼 OWNER·ADMIN만 */
     apps: {
+      /** 이 상점에 설치할 수 있는 앱 — 앱 목록·상세(아이콘·README·Scope·Hook·설정 필드) */
+      catalog: {
+        list: () => storeHttp.request("GET", "/apps/catalog", z.array(storeAppSchema)),
+        get: (appId: string) =>
+          storeHttp.request("GET", path`/apps/catalog/${appId}`, storeAppDetailSchema),
+      },
       installations: {
-        /** 설치 결과(accounts 동의 화면의 1회용 JWT)를 내 설치를 만든다 */
-        install: (result: string) =>
+        /**
+         * 설치 — 문자열이면 accounts 동의 화면의 설치 결과(1회용 JWT), 객체면 상점 플랫폼 설치 화면에서 동의한 앱과 설정이다
+         */
+        install: (
+          input: string | { appId: string; settings?: AppInstallationSettingsUpdate["values"] },
+        ) =>
           storeHttp.request("POST", "/apps/installations", appInstallationSchema, {
-            body: appInstallRequestSchema.parse({ result }),
+            body: appInstallRequestSchema.parse(
+              typeof input === "string" ? { result: input } : input,
+            ),
           }),
         list: () => storeHttp.request("GET", "/apps/installations", z.array(appInstallationSchema)),
         get: (installationId: string) =>
@@ -1455,6 +1470,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(

package/src/schemas/app-manifest.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
 import { isStoreScope, STORE_SCOPE_RESOURCES, type StoreScopeResource } from "./scope";
 import { describeScope } from "./scope-descriptions";
-import { KNOWN_WEBHOOK_EVENT_TYPES, type WebhookEventType } from "./webhook-event";
+import {
+  KNOWN_WEBHOOK_EVENT_TYPES,
+  type WebhookEventOf,
+  type WebhookEventType,
+} from "./webhook-event";
 
 /**
  * 서드파티 앱 매니페스트 `sayren.app.json` (이슈 #22) — CLI(`sayren app`)·api(빌드 `VERIFY`·버전 판정·동의 화면 자료)·런타임이
@@ -84,6 +88,36 @@ export const APP_LIFECYCLE_EVENT_TYPES = [
 export type AppLifecycleEventType = (typeof APP_LIFECYCLE_EVENT_TYPES)[number];
 export type AppEventType = WebhookEventType | AppLifecycleEventType;
 
+/**
+ * 생명주기 이벤트의 `data`(매뉴얼 「앱 이벤트」 표). api가 보내는 값과 `@sayren/app`의 핸들러 타입이 이 한 곳을 쓴다.
+ * 키를 바꾸면 앱 코드가 깨진다 — 더하기만 한다
+ */
+export interface AppLifecycleEventDataMap {
+  "APP.INSTALLED": {
+    installationId: string;
+    storeId: string;
+    versionNumber: number;
+    grantedScopes: string[];
+  };
+  "APP.SETTINGS_UPDATED": { installationId: string; storeId: string; changedKeys: string[] };
+  "APP.SCOPES_UPDATED": {
+    installationId: string;
+    storeId: string;
+    versionNumber: number;
+    grantedScopes: string[];
+  };
+  "APP.UNINSTALLED": { installationId: string; storeId: string };
+  "APP.STORE_REDACT": { installationId: string; storeId: string };
+  "APP.CUSTOMER_REDACT": { storeId: string; memberId: string };
+}
+
+/** 이벤트 타입 하나의 `data` — 웹훅 이벤트는 `WebhookEventOf<T>["data"]`, 생명주기 이벤트는 위 표다 */
+export type AppEventDataOf<T extends AppEventType> = T extends AppLifecycleEventType
+  ? AppLifecycleEventDataMap[T]
+  : T extends WebhookEventType
+    ? WebhookEventOf<T>["data"]
+    : never;
+
 /**
  * 이벤트를 받는 데 필요한 스코프 — 동의 스코프가 이것을 덮지 못하면 분배하지 않고, 매니페스트 `scopes`가 덮지 못하면 빌드가 실패한다.
  * 생명주기 이벤트는 스코프가 없다(null). 새 웹훅 이벤트를 더하면 이 표도 더해야 테스트가 통과한다
@@ -200,6 +234,37 @@ export const APP_SECRETS_MAX = 20;
 export const APP_EVENTS_MAX = 50;
 export const APP_NETWORK_HOSTS_MAX = 20;
 
+/** 앱 목록에 보이는 아이콘·README(#22 앱 목록 시안) — 앱 폴더의 파일을 `sayren app deploy`가 버전과 함께 올린다 */
+export const APP_ICON_MAX_BYTES = 256 * 1024;
+export const APP_ICON_MIN_PX = 512;
+export const APP_README_MAX_BYTES = 64 * 1024;
+export const APP_ICON_CONTENT_TYPES = ["image/png", "image/svg+xml"] as const;
+export type AppIconContentType = (typeof APP_ICON_CONTENT_TYPES)[number];
+const APP_FOLDER_FILE = /^(?!\/)(?!.*\.\.)[A-Za-z0-9._/-]+$/;
+
+/** 아이콘 파일 검사 — 문제가 없으면 null. CLI `app verify`·`deploy`와 api 빌드 `VERIFY`가 같은 규칙을 쓴다 */
+export function appIconProblem(bytes: Uint8Array, contentType: AppIconContentType): string | null {
+  if (bytes.byteLength === 0) return "아이콘 파일이 비어 있습니다";
+  if (bytes.byteLength > APP_ICON_MAX_BYTES) {
+    return `아이콘이 ${Math.ceil(bytes.byteLength / 1024)}KB입니다. 상한은 ${APP_ICON_MAX_BYTES / 1024}KB입니다`;
+  }
+  if (contentType === "image/svg+xml") {
+    const head = new TextDecoder().decode(bytes.subarray(0, 1024));
+    return /<svg[\s>]/i.test(head) ? null : "SVG 파일이 아닙니다";
+  }
+  const signature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+  if (bytes.byteLength < 24 || signature.some((b, i) => bytes[i] !== b))
+    return "PNG 파일이 아닙니다";
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16);
+  const height = view.getUint32(20);
+  if (width !== height) return `아이콘은 정사각형이어야 합니다(지금 ${width}×${height})`;
+  if (width < APP_ICON_MIN_PX) {
+    return `아이콘은 ${APP_ICON_MIN_PX}×${APP_ICON_MIN_PX} 이상이어야 합니다(지금 ${width}×${height})`;
+  }
+  return null;
+}
+
 export const appManifestSchema = z.strictObject({
   handle: appHandleSchema,
   name: z.string().trim().min(1).max(60),
@@ -207,6 +272,18 @@ export const appManifestSchema = z.strictObject({
   /** https 이미지 주소. 동의 화면·상점 플랫폼 목록에 보인다 */
   iconUrl: z.url().startsWith("https://").optional(),
   supportEmail: z.email().optional(),
+  /** 앱 폴더의 아이콘 파일(PNG·SVG, 정사각형, PNG는 512px 이상, 256KB 이하). 있으면 `iconUrl`보다 먼저 보인다 */
+  icon: z
+    .string()
+    .regex(APP_FOLDER_FILE)
+    .refine((path) => /\.(png|svg)$/i.test(path), { message: "아이콘은 .png 또는 .svg 파일입니다" })
+    .optional(),
+  /** 앱 상세에 보일 README(마크다운, 64KB 이하). 적지 않으면 앱 폴더의 README.md를 쓴다 */
+  readme: z
+    .string()
+    .regex(APP_FOLDER_FILE)
+    .refine((path) => /\.md$/i.test(path), { message: "README는 .md 파일입니다" })
+    .optional(),
   /** 실행 위치 — A1은 코드 업로드 앱만. 외부 런타임(`external`)은 A3에서 연다 */
   runtime: z.literal("code").default("code"),
   /** 설치 때 전체 동의하는 스코프 */

package/src/schemas/apps.ts

@@ -1,10 +1,13 @@
 import { z } from "zod";
 import {
+  APP_ICON_CONTENT_TYPES,
+  APP_README_MAX_BYTES,
   type AppCapabilities,
   appEventTypeSchema,
   appHandleSchema,
   appSettingFieldSchema,
 } from "./app-manifest";
+import { webhookDeliveryErrorCodeSchema, webhookDeliveryStatusSchema } from "./misc";
 
 /**
  * 설치 앱 관리 API 계약 (이슈 #22) — `/v1/apps/installations/**`(상점이 설치한 앱), `/v1/app/installation`(설치 토큰 자기 조회).
@@ -69,6 +72,16 @@ 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),
+    })
+    .nullable()
+    .optional()
+    .describe("재동의가 필요한 새 버전이 요청하는 권한·외부 호스트·이벤트(전체). 없으면 null"),
   grantedScopes: z.array(z.string()).describe("동의한 스코프"),
   grantedNetworkHosts: z.array(z.string()).describe("동의한 외부 호출 호스트"),
   events: z.array(appEventTypeSchema).describe("이 설치가 받는 이벤트"),
@@ -82,12 +95,84 @@ export const appInstallationSchema = z.object({
 });
 export type AppInstallation = z.infer<typeof appInstallationSchema>;
 
-/** `POST /v1/apps/installations` — accounts 설치 동의 결과(1회용 JWT)를 낸다(상점 플랫폼 전용) */
-export const appInstallRequestSchema = z.object({
-  result: z.string().min(1).describe("accounts가 발급한 설치 결과 JWT(`typ: sayren-install+jwt`)"),
+/** 실행 기록 한 줄 — 앱에 보낸 이벤트 하나의 전송 결과. 로그 본문은 개발자만 본다(매뉴얼 「앱 설치와 관리」) */
+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). 개발자 포털 [내 상점에 설치]가 이 길로 온다
+ * - `{ appId, settings }`: 상점 플랫폼 앱 목록 › 설치 화면에서 동의하고 설정까지 채워 바로 설치한다
+ */
+export const appInstallRequestSchema = z.union([
+  z.object({
+    result: z
+      .string()
+      .min(1)
+      .describe("accounts가 발급한 설치 결과 JWT(`typ: sayren-install+jwt`)"),
+  }),
+  z.object({
+    appId: z.string().min(1),
+    settings: z
+      .record(z.string(), settingsValueSchema)
+      .default({})
+      .describe("설치와 함께 저장할 설정. 비밀 필드도 여기서 넣는다"),
+  }),
+]);
 export type AppInstallRequest = z.infer<typeof appInstallRequestSchema>;
 
+/** 앱 목록 정보 — 현재 버전이 올린 아이콘·README(없으면 매니페스트 `iconUrl`) */
+export const appListingSchema = z.object({
+  description: z.string().nullable(),
+  iconUrl: z
+    .string()
+    .nullable()
+    .describe("아이콘 주소. 앱 폴더에서 올린 아이콘은 data URI, 매니페스트 `iconUrl`은 https 주소"),
+  readme: z.string().nullable().describe("README 마크다운 원문"),
+});
+export type AppListing = z.infer<typeof appListingSchema>;
+
+/** `GET /v1/apps/catalog` — 이 상점에 설치할 수 있는 앱(A1: 내가 속한 개발자 조직의 앱) */
+export const storeAppSchema = z.object({
+  appId: z.string(),
+  handle: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  iconUrl: z.string().nullable(),
+  developerName: z.string(),
+  versionNumber: z.number().int().describe("현재 버전"),
+  installationId: z.string().nullable().describe("이 상점에 설치돼 있으면 설치 id"),
+});
+export type StoreApp = z.infer<typeof storeAppSchema>;
+
+/** `GET /v1/apps/catalog/{appId}` — 앱 상세·설치 화면 */
+export const storeAppDetailSchema = storeAppSchema.extend({
+  readme: z.string().nullable(),
+  supportEmail: z.string().nullable(),
+  scopes: z.array(z.string()).describe("설치 때 동의하는 스코프(Scope)"),
+  events: z.array(appEventTypeSchema).describe("받는 이벤트(Hook)"),
+  networkHosts: z.array(z.string()).describe("앱이 데이터를 보내는 외부 호스트"),
+  settings: z.record(z.string(), appSettingFieldSchema).describe("설치 때 채우는 설정 필드"),
+  updatedAt: z.string().nullable().describe("현재 버전을 release한 시각"),
+});
+export type StoreAppDetail = z.infer<typeof storeAppDetailSchema>;
+
 /** `POST /v1/apps/installations/{id}/session` — 앱 화면 iframe이 쓸 세션 토큰(5분) */
 export const appSessionSchema = z.object({
   token: z.string(),
@@ -168,6 +253,11 @@ export const appVersionSchema = z.object({
     secretSettings: z.array(z.string()),
   }),
   build: appBuildSchema.nullable(),
+  listing: appListingSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("이 버전이 올린 아이콘·설명·README"),
   releasedAt: z.string().nullable(),
   revokedAt: z.string().nullable(),
   createdAt: z.string(),
@@ -218,6 +308,16 @@ export const appArtifactUploadSchema = z.object({
     .max(2_000)
     .default([]),
   message: z.string().trim().max(200).optional(),
+  /** 앱 폴더의 아이콘·README — 매니페스트 `icon`·`readme`(없으면 README.md)를 CLI가 싣는다 */
+  listing: z
+    .object({
+      icon: z
+        .object({ contentType: z.enum(APP_ICON_CONTENT_TYPES), content: z.string().min(1) })
+        .nullable()
+        .default(null),
+      readme: z.string().max(APP_README_MAX_BYTES).nullable().default(null),
+    })
+    .default({ icon: null, readme: null }),
 });
 export type AppArtifactUpload = z.infer<typeof appArtifactUploadSchema>;