@yoonion/mimi-seed-mcp 0.13.16 → 0.13.18

package/README.md

@@ -78,8 +78,8 @@ export ANTHROPIC_API_KEY=sk-ant-...
 
 | 영역 | 도구 수 | 주요 도구 |
 |------|---------|-----------|
-| App Store Connect | 50 | `appstore_submit_for_review` / `appstore_upload_screenshot` / `appstore_update_product_review_note` / `appstore_upload_product_review_screenshot` |
-| Google Play | 33 | `playstore_submit_release` / `playstore_promote_release` / `playstore_replace_images` / `playstore_reply_review` / `playstore_verify_service_account` |
+| App Store Connect | 61 | `appstore_submit_for_review` / `appstore_upload_screenshot` / `appstore_update_product_review_note` / `appstore_upload_product_review_screenshot` |
+| Google Play | 37 | `playstore_submit_release` / `playstore_promote_release` / `playstore_replace_images` / `playstore_reply_review` / `playstore_verify_service_account` |
 | Firebase | 20 | `firebase_create_project` / `firebase_create_android_app` / `firebase_get_android_config` / `firebase_create_ios_app` |
 | AdMob | 7 | `admob_list_apps` / `admob_create_ad_unit` / `admob_get_today_earnings` / `admob_get_report` |
 | CI/CD (GitHub Actions · GitLab) | 6 | `ci_trigger_build` / `ci_get_build_status` / `ci_list_workflows` / `ci_cancel_build` |

package/assets/agent-guide.md

@@ -56,7 +56,10 @@ you can paste. Pick the row for the job; batching two rows in one `select:` call
 | App Store / TestFlight | `select:appstore_list_apps,appstore_verify_credentials,appstore_get_app,appstore_list_versions,appstore_create_version,appstore_get_metadata,appstore_update_whats_new,appstore_list_builds,appstore_attach_build,appstore_attach_latest_build,appstore_list_beta_groups,appstore_submit_for_review,appstore_check_submission_risks,appstore_plan_release` |
 | App Store release control (after approval) | `select:appstore_release_status,appstore_release_version,appstore_update_release_type,appstore_phased_release,appstore_list_versions` |
 | Pre-submission declarations (both stores) | `select:appstore_get_age_rating,appstore_update_age_rating,appstore_declare_encryption,appstore_get_availability,appstore_set_territory_availability,playstore_upload_data_safety` |
+| TestFlight external testing | `select:appstore_beta_status,appstore_update_beta_review_detail,appstore_update_beta_test_info,appstore_update_whats_to_test,appstore_submit_beta_review,appstore_set_beta_group_build,appstore_add_beta_testers,appstore_notify_beta_testers,appstore_list_beta_groups,appstore_list_builds` |
 | App Store review submission (the bundle) | `select:appstore_list_review_submissions,appstore_add_version_to_review_submission,appstore_remove_review_submission_item,appstore_update_version_string,appstore_cancel_review` |
+| App Store preview videos | `select:appstore_list_previews,appstore_upload_preview,appstore_delete_preview,appstore_get_metadata` |
+| Play post-release recovery | `select:playstore_list_recovery_actions,playstore_create_recovery_action,playstore_deploy_recovery_action,playstore_cancel_recovery_action,playstore_list_tracks` |
 | App Store screenshots | `select:appstore_list_app_info_localizations,appstore_get_metadata,appstore_list_screenshots,appstore_upload_screenshot,appstore_delete_screenshot,appstore_delete_screenshot_set,screenshot_validate` |
 | App Store app info + review notes | `select:appstore_get_app_info,appstore_update_app_info_localization,appstore_create_app_info_localization,appstore_update_localization,appstore_get_review_notes,appstore_update_review_notes` |
 | App Store reviews | `select:appstore_list_reviews,appstore_reply_review,generate_review_reply` |

package/dist/appstore/declarations.js

@@ -5,7 +5,7 @@
 //   판매 지역 (appAvailabilityV2 / territoryAvailabilities): 지역별 available·출시일
 //
 // Play 쪽 대응물(데이터 안전 CSV)은 playstore/tools.ts 에 있다 — 자격증명 계통이 달라서 파일을 나눴다.
-import { V1_BASE, V2_BASE, apiRequest, authHeadersOrThrow } from './http.js';
+import { V1_BASE, V2_BASE, apiRequest, authHeadersOrThrow, isNotFound } from './http.js';
 async function get(base, path, params) {
     const headers = await authHeadersOrThrow();
     const query = params ? `?${new URLSearchParams(params).toString()}` : '';
@@ -33,12 +33,21 @@ async function resolveAppInfoId(appId) {
 }
 export async function getAgeRating(appId) {
     const appInfoId = await resolveAppInfoId(appId);
-    const data = await get(V1_BASE, `/appInfos/${appInfoId}/ageRatingDeclaration`);
-    return {
-        appInfoId,
-        declarationId: data.data?.id,
-        declaration: data.data?.attributes ?? {},
-    };
+    // 선언 리소스가 아직 없는 앱이 있다 — 그때는 404 다. 에러 대신 "없음"으로 돌려주고
+    // updateAgeRating 이 사람이 읽을 안내를 내도록 한다.
+    try {
+        const data = await get(V1_BASE, `/appInfos/${appInfoId}/ageRatingDeclaration`);
+        return {
+            appInfoId,
+            declarationId: data.data?.id,
+            declaration: data.data?.attributes ?? {},
+        };
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return { appInfoId, declarationId: undefined, declaration: {} };
+        throw err;
+    }
 }
 /**
  * 연령 등급 설문 갱신 (PATCH /v1/ageRatingDeclarations/{id}).

package/dist/appstore/http.d.ts

@@ -3,3 +3,11 @@ export declare const V2_BASE = "https://api.appstoreconnect.apple.com/v2";
 export type AppStoreProductType = 'subscription' | 'consumable' | 'non_consumable';
 export declare function authHeadersOrThrow(): Promise<Record<string, string>>;
 export declare function apiRequest<T>(base: string, resourcePath: string, authHeaders: Record<string, string>, init: RequestInit): Promise<T>;
+/**
+ * "리소스 없음"인지 **상태 코드로** 판별한다.
+ *
+ * friendlyAppStoreError 가 cause.status 에 실제 HTTP 상태를 붙여준다. 메시지 문자열로
+ * 404 를 찾으면 본문에 'not found'/'404' 가 섞인 403·409 까지 "없음"으로 삼켜서,
+ * 권한 오류가 조용히 빈 결과로 둔갑한다. 상태를 못 읽는 경우에만 문자열로 폴백한다.
+ */
+export declare function isNotFound(err: unknown): boolean;

package/dist/appstore/http.js

@@ -26,3 +26,16 @@ export async function apiRequest(base, resourcePath, authHeaders, init) {
     const text = await response.text();
     return (text ? JSON.parse(text) : { ok: true });
 }
+/**
+ * "리소스 없음"인지 **상태 코드로** 판별한다.
+ *
+ * friendlyAppStoreError 가 cause.status 에 실제 HTTP 상태를 붙여준다. 메시지 문자열로
+ * 404 를 찾으면 본문에 'not found'/'404' 가 섞인 403·409 까지 "없음"으로 삼켜서,
+ * 권한 오류가 조용히 빈 결과로 둔갑한다. 상태를 못 읽는 경우에만 문자열로 폴백한다.
+ */
+export function isNotFound(err) {
+    const cause = err?.cause;
+    if (typeof cause?.status === 'number')
+        return cause.status === 404;
+    return /App Store API 404\b/.test(err?.message ?? '');
+}

package/dist/appstore/previews.d.ts

@@ -0,0 +1,41 @@
+export interface PreviewRow {
+    id: string;
+    fileName?: string;
+    fileSize?: number;
+    state?: string;
+    previewFrameTimeCode?: string;
+    videoUrl?: string;
+}
+export interface PreviewSetRow {
+    id: string;
+    previewType?: string;
+    previews: PreviewRow[];
+}
+/** 로케일의 미리보기 세트 + 각 동영상 상태. 업로드 후 인코딩 확인도 여기서 한다. */
+export declare function listPreviewSets(localizationId: string): Promise<PreviewSetRow[]>;
+/**
+ * 미리보기 동영상 업로드. `previewFrameTimeCode` 는 포스터 프레임 시각 (HH:MM:SS:FF).
+ *
+ * Apple 제약(업로드 후 인코딩 단계에서 거부될 수 있는 것들):
+ *   길이 15~30초 · previewType 별 해상도 고정 · 로케일·타입당 최대 3개.
+ */
+export declare function uploadPreview(args: {
+    localizationId: string;
+    previewType: string;
+    filePath: string;
+    previewFrameTimeCode?: string;
+}): Promise<{
+    id: string;
+    fileName: string;
+    fileSize: number;
+    previewType: string;
+    state?: string;
+}>;
+export declare function deletePreview(previewId: string): Promise<{
+    ok: true;
+    id: string;
+}>;
+export declare function deletePreviewSet(setId: string): Promise<{
+    ok: true;
+    id: string;
+}>;

package/dist/appstore/previews.js

@@ -0,0 +1,190 @@
+// App Store 제품 페이지 미리보기 **동영상** (appPreviewSets / appPreviews).
+//
+// 업로드 절차는 스크린샷과 같은 4단계다 (screenshots.ts 와 같은 기계):
+//   1. set 확보  POST /appPreviewSets              (previewType 별로 하나)
+//   2. 예약      POST /appPreviews                 → uploadOperations[]
+//   3. 업로드    PUT  각 operation URL (offset/length 로 조각내서)
+//   4. 커밋      PATCH /appPreviews/{id}           { uploaded, sourceFileChecksum }
+//
+// 스크린샷과 다른 점: 커밋 뒤 Apple 이 **인코딩**을 돌린다. 그래서 업로드 성공 ≠ 노출 가능이고,
+// assetDeliveryState 를 따로 확인해야 한다. previewFrameTimeCode 로 포스터 프레임도 고른다.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { getAuthHeaders } from './auth.js';
+const BASE = 'https://api.appstoreconnect.apple.com/v1';
+async function req(pathOrUrl, init = {}) {
+    const headers = await getAuthHeaders();
+    if (!headers) {
+        throw new Error([
+            '❌ App Store Connect 인증이 필요해.',
+            '',
+            '터미널에서 실행:',
+            '  npx -p @yoonion/mimi-seed-mcp mimi-seed-appstore-auth',
+        ].join('\n'));
+    }
+    const url = pathOrUrl.startsWith('http') ? pathOrUrl : `${BASE}${pathOrUrl}`;
+    const res = await fetch(url, { ...init, headers: { ...headers, ...(init.headers ?? {}) } });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`App Store API ${res.status} ${init.method ?? 'GET'} ${pathOrUrl}: ${body}`);
+    }
+    const text = await res.text();
+    return (text ? JSON.parse(text) : null);
+}
+/** 로케일의 미리보기 세트 + 각 동영상 상태. 업로드 후 인코딩 확인도 여기서 한다. */
+export async function listPreviewSets(localizationId) {
+    const data = await req(`/appStoreVersionLocalizations/${localizationId}/appPreviewSets` +
+        `?include=appPreviews` +
+        `&fields[appPreviewSets]=previewType,appPreviews` +
+        `&fields[appPreviews]=fileName,fileSize,assetDeliveryState,previewFrameTimeCode,videoUrl`);
+    const included = data?.included ?? [];
+    return (data?.data ?? []).map((s) => {
+        const ids = (s.relationships?.appPreviews?.data ?? []).map((p) => p.id);
+        return {
+            id: s.id,
+            previewType: s.attributes?.previewType,
+            previews: included
+                .filter((i) => i.type === 'appPreviews' && ids.includes(i.id))
+                .map((i) => ({
+                id: i.id,
+                fileName: i.attributes?.fileName,
+                fileSize: i.attributes?.fileSize,
+                state: i.attributes?.assetDeliveryState?.state,
+                previewFrameTimeCode: i.attributes?.previewFrameTimeCode,
+                videoUrl: i.attributes?.videoUrl,
+            })),
+        };
+    });
+}
+async function ensurePreviewSet(localizationId, previewType) {
+    const sets = await listPreviewSets(localizationId);
+    const hit = sets.find((s) => s.previewType === previewType);
+    if (hit)
+        return hit.id;
+    const created = await req('/appPreviewSets', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            data: {
+                type: 'appPreviewSets',
+                attributes: { previewType },
+                relationships: {
+                    appStoreVersionLocalization: {
+                        data: { type: 'appStoreVersionLocalizations', id: localizationId },
+                    },
+                },
+            },
+        }),
+    });
+    return created.data.id;
+}
+async function uploadChunks(absPath, ops) {
+    const fd = fs.openSync(absPath, 'r');
+    try {
+        for (const op of ops) {
+            // 파일 전체를 메모리에 올리지 않는다 — 동영상은 수백 MB 가 될 수 있다.
+            const chunk = Buffer.alloc(op.length);
+            fs.readSync(fd, chunk, 0, op.length, op.offset);
+            const headers = {};
+            for (const h of op.requestHeaders ?? [])
+                headers[h.name] = h.value;
+            const res = await fetch(op.url, { method: op.method ?? 'PUT', headers, body: chunk });
+            if (!res.ok) {
+                throw new Error(`미리보기 업로드 실패 (offset ${op.offset}): ${res.status} ${await res.text()}`);
+            }
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** 확장자로 추정한 mimeType. Apple 은 없어도 받지만 있으면 처리 실패가 줄어든다. */
+function guessMimeType(fileName) {
+    const ext = path.extname(fileName).toLowerCase();
+    if (ext === '.mp4')
+        return 'video/mp4';
+    if (ext === '.mov')
+        return 'video/quicktime';
+    if (ext === '.m4v')
+        return 'video/x-m4v';
+    return undefined;
+}
+/**
+ * 미리보기 동영상 업로드. `previewFrameTimeCode` 는 포스터 프레임 시각 (HH:MM:SS:FF).
+ *
+ * Apple 제약(업로드 후 인코딩 단계에서 거부될 수 있는 것들):
+ *   길이 15~30초 · previewType 별 해상도 고정 · 로케일·타입당 최대 3개.
+ */
+export async function uploadPreview(args) {
+    const { localizationId, previewType, filePath, previewFrameTimeCode } = args;
+    if (!path.isAbsolute(filePath))
+        throw new Error(`filePath 는 절대경로여야 한다: ${filePath}`);
+    if (!fs.existsSync(filePath))
+        throw new Error(`파일이 존재하지 않는다: ${filePath}`);
+    const fileName = path.basename(filePath);
+    const fileSize = fs.statSync(filePath).size;
+    if (fileSize === 0)
+        throw new Error('빈 파일이다.');
+    const setId = await ensurePreviewSet(localizationId, previewType);
+    const mimeType = guessMimeType(fileName);
+    const reserved = await req('/appPreviews', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            data: {
+                type: 'appPreviews',
+                attributes: {
+                    fileName,
+                    fileSize,
+                    ...(mimeType ? { mimeType } : {}),
+                    ...(previewFrameTimeCode ? { previewFrameTimeCode } : {}),
+                },
+                relationships: { appPreviewSet: { data: { type: 'appPreviewSets', id: setId } } },
+            },
+        }),
+    });
+    const previewId = reserved.data.id;
+    const ops = reserved.data.attributes?.uploadOperations ?? [];
+    if (ops.length === 0)
+        throw new Error('uploadOperations 가 비어 있다 — Apple 응답 형식 확인 필요.');
+    await uploadChunks(filePath, ops);
+    // 체크섬은 전체 파일 기준이라 스트리밍으로 계산한다 (메모리에 다 올리지 않는다).
+    const md5 = await new Promise((resolve, reject) => {
+        const hash = crypto.createHash('md5');
+        fs.createReadStream(filePath)
+            .on('data', (c) => hash.update(c))
+            .on('end', () => resolve(hash.digest('hex')))
+            .on('error', reject);
+    });
+    const committed = await req(`/appPreviews/${previewId}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            data: {
+                type: 'appPreviews',
+                id: previewId,
+                attributes: {
+                    uploaded: true,
+                    sourceFileChecksum: md5,
+                    ...(previewFrameTimeCode ? { previewFrameTimeCode } : {}),
+                },
+            },
+        }),
+    });
+    return {
+        id: previewId,
+        fileName,
+        fileSize,
+        previewType,
+        state: committed?.data?.attributes?.assetDeliveryState?.state,
+    };
+}
+export async function deletePreview(previewId) {
+    await req(`/appPreviews/${previewId}`, { method: 'DELETE' });
+    return { ok: true, id: previewId };
+}
+export async function deletePreviewSet(setId) {
+    await req(`/appPreviewSets/${setId}`, { method: 'DELETE' });
+    return { ok: true, id: setId };
+}

package/dist/appstore/release.js

@@ -6,7 +6,7 @@
 //   2. 만들어 둔 버전의 releaseType 을 나중에 바꾸기 (PATCH appStoreVersions)
 //   3. 단계적 출시 시작·일시중지·재개·즉시완료 (phasedRelease)
 // Play 는 userFraction/halted 로 3번이 되는데 iOS 만 비어 있었다.
-import { V1_BASE, apiRequest, authHeadersOrThrow } from './http.js';
+import { V1_BASE, apiRequest, authHeadersOrThrow, isNotFound } from './http.js';
 /** 각 상태가 "지금 출시" 요청을 받을 수 있는지 + 사람이 읽을 설명. */
 const STATE_NOTE = {
     PENDING_DEVELOPER_RELEASE: '심사 통과 후 개발자 출시 대기 — 지금 출시할 수 있다.',
@@ -60,7 +60,7 @@ async function getPhasedRelease(versionId) {
         };
     }
     catch (err) {
-        if (/404|not found|NOT_FOUND/i.test(err.message))
+        if (isNotFound(err))
             return null;
         throw err;
     }

package/dist/appstore/testflight.d.ts

@@ -0,0 +1,89 @@
+export interface BetaStatus {
+    buildId: string;
+    internalState?: string;
+    externalState?: string;
+    note: string;
+    autoNotifyEnabled?: boolean;
+    submissionState?: string;
+    whatsToTestLocales: string[];
+    reviewDetail?: {
+        id: string;
+        complete: boolean;
+        missing: string[];
+    };
+    testInfoLocales?: string[];
+}
+/**
+ * 외부 테스트 제출 전 "뭐가 비었는지"를 한 번에 본다.
+ * appId 를 함께 주면 앱 단위 항목(심사 정보·테스트 정보)까지 검사한다.
+ */
+export declare function getBetaStatus(args: {
+    buildId: string;
+    appId?: string;
+}): Promise<BetaStatus>;
+/** 베타 심사 정보 (앱 단위, 단일 리소스). PATCH 만 가능하다 — Apple 이 앱 생성 때 만들어 둔다. */
+export declare function updateBetaReviewDetail(args: {
+    appId: string;
+    fields: Record<string, string | boolean | undefined>;
+}): Promise<{
+    id: string;
+    attributes: Record<string, unknown>;
+}>;
+/** 앱 단위 테스트 정보(피드백 이메일·설명 등)를 로케일별로 upsert. */
+export declare function upsertBetaTestInfo(args: {
+    appId: string;
+    locale: string;
+    fields: {
+        feedbackEmail?: string;
+        description?: string;
+        marketingUrl?: string;
+        privacyPolicyUrl?: string;
+    };
+}): Promise<{
+    id: string;
+    created: boolean;
+    locale: string;
+}>;
+/** 빌드 단위 What to Test 를 로케일별로 upsert. */
+export declare function upsertWhatsToTest(args: {
+    buildId: string;
+    locale: string;
+    whatsNew: string;
+}): Promise<{
+    id: string;
+    created: boolean;
+    locale: string;
+}>;
+/** 빌드를 베타 심사에 제출 (외부 테스터 배포 전 필수). */
+export declare function submitBetaReview(buildId: string): Promise<{
+    submissionId: string;
+    state?: string;
+}>;
+/** 베타 그룹에 빌드를 붙이거나 뗀다. 외부 그룹이면 실제 배포/회수다. */
+export declare function setBetaGroupBuild(args: {
+    groupId: string;
+    buildId: string;
+    action: 'add' | 'remove';
+}): Promise<{
+    groupId: string;
+    buildId: string;
+    action: string;
+}>;
+/** 테스터 초대. 이미 등록된 이메일은 409 가 나므로 개별 결과로 보고한다. */
+export declare function addBetaTesters(args: {
+    groupId: string;
+    testers: Array<{
+        email: string;
+        firstName?: string;
+        lastName?: string;
+    }>;
+}): Promise<Array<{
+    email: string;
+    ok: boolean;
+    testerId?: string;
+    error?: string;
+}>>;
+/** 이미 배포된 빌드에 대해 테스터에게 알림을 다시 보낸다. */
+export declare function notifyBetaTesters(buildId: string): Promise<{
+    notificationId: string;
+}>;

package/dist/appstore/testflight.js

@@ -0,0 +1,199 @@
+// TestFlight 외부 테스트 — 심사 제출과 배포.
+//
+// 내부 테스터(팀)는 빌드가 처리되면 바로 받지만, **외부 테스터는 Apple 베타 심사를 통과해야** 받는다.
+// 그 심사에 필요한 것이 세 갈래로 흩어져 있다:
+//   앱 단위  betaAppReviewDetail   연락처·데모 계정·심사 노트
+//   앱 단위  betaAppLocalizations  피드백 이메일·앱 설명 (로케일별)
+//   빌드 단위 betaBuildLocalizations  What to Test (로케일별)
+// 하나라도 비면 제출이 막히거나 반려된다. 그래서 상태 조회를 "뭐가 비었는지" 중심으로 만든다.
+import { V1_BASE, apiRequest, authHeadersOrThrow, isNotFound } from './http.js';
+/** 외부 빌드 상태 → 사람이 읽을 뜻 + 다음 행동. */
+const EXTERNAL_STATE = {
+    PROCESSING: '업로드 처리 중 — 끝날 때까지 기다린다.',
+    PROCESSING_EXCEPTION: '처리 실패 — 빌드를 다시 업로드해야 한다.',
+    MISSING_EXPORT_COMPLIANCE: '수출 규정 정보 없음 — appstore_declare_encryption 으로 선언하거나 Info.plist 에 ITSAppUsesNonExemptEncryption 을 넣는다.',
+    READY_FOR_BETA_SUBMISSION: '베타 심사 제출 가능 — appstore_submit_beta_review.',
+    WAITING_FOR_BETA_REVIEW: '베타 심사 대기열.',
+    IN_BETA_REVIEW: '베타 심사 진행 중.',
+    BETA_APPROVED: '베타 심사 통과 — 외부 그룹에 배포할 수 있다.',
+    BETA_REJECTED: '베타 심사 반려 — 사유 확인 후 수정하고 재제출.',
+    READY_FOR_BETA_TESTING: '테스트 준비 완료.',
+    IN_BETA_TESTING: '외부 테스트 중.',
+    EXPIRED: '빌드 만료 — 새 빌드가 필요하다.',
+};
+async function get(path, params) {
+    const headers = await authHeadersOrThrow();
+    const query = params ? `?${new URLSearchParams(params).toString()}` : '';
+    return apiRequest(V1_BASE, `${path}${query}`, headers, { method: 'GET' });
+}
+async function send(method, path, body) {
+    const headers = await authHeadersOrThrow();
+    return apiRequest(V1_BASE, path, headers, {
+        method,
+        ...(body === undefined
+            ? {}
+            : { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }),
+    });
+}
+/** to-one 관계는 없을 때 data:null 또는 404 로 온다. */
+async function getOrNull(path) {
+    try {
+        const r = await get(path);
+        return r.data ?? null;
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return null;
+        throw err;
+    }
+}
+/**
+ * 외부 테스트 제출 전 "뭐가 비었는지"를 한 번에 본다.
+ * appId 를 함께 주면 앱 단위 항목(심사 정보·테스트 정보)까지 검사한다.
+ */
+export async function getBetaStatus(args) {
+    const { buildId, appId } = args;
+    const detail = await getOrNull(`/builds/${buildId}/buildBetaDetail`);
+    const submission = await getOrNull(`/builds/${buildId}/betaAppReviewSubmission`);
+    const locs = await get(`/builds/${buildId}/betaBuildLocalizations`);
+    const externalState = detail?.attributes?.externalBuildState;
+    const status = {
+        buildId,
+        internalState: detail?.attributes?.internalBuildState,
+        externalState,
+        note: (externalState && EXTERNAL_STATE[externalState]) || '',
+        autoNotifyEnabled: detail?.attributes?.autoNotifyEnabled,
+        submissionState: submission?.attributes?.betaReviewState,
+        whatsToTestLocales: (locs.data ?? [])
+            .filter((l) => (l.attributes?.whatsNew ?? '').trim().length > 0)
+            .map((l) => l.attributes?.locale ?? '?'),
+    };
+    if (appId) {
+        const rd = await getOrNull(`/apps/${appId}/betaAppReviewDetail`);
+        if (rd) {
+            const a = rd.attributes ?? {};
+            const missing = [];
+            for (const f of ['contactFirstName', 'contactLastName', 'contactPhone', 'contactEmail']) {
+                if (!a[f])
+                    missing.push(f);
+            }
+            if (a.demoAccountRequired && (!a.demoAccountName || !a.demoAccountPassword)) {
+                missing.push('demoAccountName/demoAccountPassword (demoAccountRequired=true 인데 비어 있음)');
+            }
+            status.reviewDetail = { id: rd.id, complete: missing.length === 0, missing };
+        }
+        const appLocs = await get(`/apps/${appId}/betaAppLocalizations`);
+        status.testInfoLocales = (appLocs.data ?? []).map((l) => l.attributes?.locale ?? '?');
+    }
+    return status;
+}
+/** 베타 심사 정보 (앱 단위, 단일 리소스). PATCH 만 가능하다 — Apple 이 앱 생성 때 만들어 둔다. */
+export async function updateBetaReviewDetail(args) {
+    const attributes = Object.fromEntries(Object.entries(args.fields).filter(([, v]) => v !== undefined));
+    if (Object.keys(attributes).length === 0)
+        throw new Error('바꿀 항목이 없다.');
+    const rd = await getOrNull(`/apps/${args.appId}/betaAppReviewDetail`);
+    if (!rd)
+        throw new Error(`앱 ${args.appId} 의 betaAppReviewDetail 을 찾지 못했다.`);
+    await send('PATCH', `/betaAppReviewDetails/${rd.id}`, {
+        data: { type: 'betaAppReviewDetails', id: rd.id, attributes },
+    });
+    const after = await getOrNull(`/apps/${args.appId}/betaAppReviewDetail`);
+    return { id: rd.id, attributes: after?.attributes ?? {} };
+}
+/** 앱 단위 테스트 정보(피드백 이메일·설명 등)를 로케일별로 upsert. */
+export async function upsertBetaTestInfo(args) {
+    const { appId, locale, fields } = args;
+    const existing = await get(`/apps/${appId}/betaAppLocalizations`);
+    const hit = (existing.data ?? []).find((l) => l.attributes?.locale === locale);
+    const attributes = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+    if (hit) {
+        await send('PATCH', `/betaAppLocalizations/${hit.id}`, {
+            data: { type: 'betaAppLocalizations', id: hit.id, attributes },
+        });
+        return { id: hit.id, created: false, locale };
+    }
+    const created = await send('POST', '/betaAppLocalizations', {
+        data: {
+            type: 'betaAppLocalizations',
+            attributes: { ...attributes, locale },
+            relationships: { app: { data: { type: 'apps', id: appId } } },
+        },
+    });
+    return { id: created.data?.id ?? '', created: true, locale };
+}
+/** 빌드 단위 What to Test 를 로케일별로 upsert. */
+export async function upsertWhatsToTest(args) {
+    const { buildId, locale, whatsNew } = args;
+    const existing = await get(`/builds/${buildId}/betaBuildLocalizations`);
+    const hit = (existing.data ?? []).find((l) => l.attributes?.locale === locale);
+    if (hit) {
+        await send('PATCH', `/betaBuildLocalizations/${hit.id}`, {
+            data: { type: 'betaBuildLocalizations', id: hit.id, attributes: { whatsNew } },
+        });
+        return { id: hit.id, created: false, locale };
+    }
+    const created = await send('POST', '/betaBuildLocalizations', {
+        data: {
+            type: 'betaBuildLocalizations',
+            attributes: { whatsNew, locale },
+            relationships: { build: { data: { type: 'builds', id: buildId } } },
+        },
+    });
+    return { id: created.data?.id ?? '', created: true, locale };
+}
+/** 빌드를 베타 심사에 제출 (외부 테스터 배포 전 필수). */
+export async function submitBetaReview(buildId) {
+    const created = await send('POST', '/betaAppReviewSubmissions', {
+        data: {
+            type: 'betaAppReviewSubmissions',
+            relationships: { build: { data: { type: 'builds', id: buildId } } },
+        },
+    });
+    return {
+        submissionId: created.data?.id ?? '',
+        state: created.data?.attributes?.betaReviewState,
+    };
+}
+/** 베타 그룹에 빌드를 붙이거나 뗀다. 외부 그룹이면 실제 배포/회수다. */
+export async function setBetaGroupBuild(args) {
+    const { groupId, buildId, action } = args;
+    await send(action === 'add' ? 'POST' : 'DELETE', `/betaGroups/${groupId}/relationships/builds`, {
+        data: [{ type: 'builds', id: buildId }],
+    });
+    return { groupId, buildId, action };
+}
+/** 테스터 초대. 이미 등록된 이메일은 409 가 나므로 개별 결과로 보고한다. */
+export async function addBetaTesters(args) {
+    const out = [];
+    for (const t of args.testers) {
+        try {
+            const created = await send('POST', '/betaTesters', {
+                data: {
+                    type: 'betaTesters',
+                    attributes: {
+                        email: t.email,
+                        ...(t.firstName ? { firstName: t.firstName } : {}),
+                        ...(t.lastName ? { lastName: t.lastName } : {}),
+                    },
+                    relationships: { betaGroups: { data: [{ type: 'betaGroups', id: args.groupId }] } },
+                },
+            });
+            out.push({ email: t.email, ok: true, testerId: created.data?.id });
+        }
+        catch (err) {
+            out.push({ email: t.email, ok: false, error: err.message });
+        }
+    }
+    return out;
+}
+/** 이미 배포된 빌드에 대해 테스터에게 알림을 다시 보낸다. */
+export async function notifyBetaTesters(buildId) {
+    const created = await send('POST', '/buildBetaNotifications', {
+        data: {
+            type: 'buildBetaNotifications',
+            relationships: { build: { data: { type: 'builds', id: buildId } } },
+        },
+    });
+    return { notificationId: created.data?.id ?? '' };
+}

package/dist/playstore/tools.d.ts

@@ -168,6 +168,44 @@ export declare function updatePurchaseOptionState(auth: OAuth2Client | JWT, pack
         state: string | undefined;
     }[];
 }>;
+export interface RecoveryTargeting {
+    /** 전체 사용자 대상. versionCodes / 범위와 함께 쓸 수 없다. */
+    allUsers?: boolean;
+    /** 특정 버전 코드들 */
+    versionCodes?: string[];
+    /** 버전 코드 범위 (start~end) */
+    versionRange?: {
+        start: string;
+        end: string;
+    };
+    /** 지역 코드 (예: KR, US) */
+    regions?: string[];
+    /** Android SDK 레벨 */
+    sdkLevels?: string[];
+}
+export declare function buildTargeting(t: RecoveryTargeting): Record<string, unknown>;
+export declare function listRecoveryActions(auth: OAuth2Client | JWT, packageName: string, versionCode?: string): Promise<{
+    id: string | null | undefined;
+    status: string | null | undefined;
+    createTime: string | null | undefined;
+    deployTime: string | null | undefined;
+    cancelTime: string | null | undefined;
+    targeting: import("googleapis/build/src/apis/androidpublisher/v3.js").androidpublisher_v3.Schema$Targeting | undefined;
+}[]>;
+/** DRAFT 상태로만 만든다 — 실제 배포는 deployRecoveryAction 이 별도로 한다. */
+export declare function createRecoveryAction(auth: OAuth2Client | JWT, packageName: string, targeting: RecoveryTargeting): Promise<{
+    id: string | null | undefined;
+    status: string | null | undefined;
+    targeting: import("googleapis/build/src/apis/androidpublisher/v3.js").androidpublisher_v3.Schema$Targeting | undefined;
+}>;
+export declare function deployRecoveryAction(auth: OAuth2Client | JWT, packageName: string, appRecoveryId: string): Promise<{
+    appRecoveryId: string;
+    deployed: boolean;
+}>;
+export declare function cancelRecoveryAction(auth: OAuth2Client | JWT, packageName: string, appRecoveryId: string): Promise<{
+    appRecoveryId: string;
+    cancelled: boolean;
+}>;
 export declare function uploadDataSafety(auth: OAuth2Client | JWT, packageName: string, safetyLabelsCsv: string): Promise<{
     packageName: string;
     bytes: number;

package/dist/playstore/tools.js

@@ -650,9 +650,79 @@ export async function updatePurchaseOptionState(auth, packageName, productId, pu
     })));
     return { productId, purchaseOptionId, action, states };
 }
-// ─── 인앱 상품 / 구독 생성은 @onesub/providers로 위임 ───
-// IAP·구독 CRUD는 onesub의 도메인 (결제 영역). 이 파일에는 메타·이미지·릴리스·리뷰만 남김.
-// 옛 createOnetimeProduct / createSubscription 구현은 onesub 위임으로 대체됐어 (index.ts 참고).
+export function buildTargeting(t) {
+    const targeting = {};
+    if (t.allUsers)
+        targeting.allUsers = { isAllUsersRequested: true };
+    if (t.versionCodes?.length)
+        targeting.versionList = { versionCodes: t.versionCodes };
+    if (t.versionRange) {
+        targeting.versionRange = {
+            versionCodeStart: t.versionRange.start,
+            versionCodeEnd: t.versionRange.end,
+        };
+    }
+    if (t.regions?.length)
+        targeting.regions = { regionCode: t.regions };
+    if (t.sdkLevels?.length)
+        targeting.androidSdks = { sdkLevels: t.sdkLevels };
+    if (Object.keys(targeting).length === 0) {
+        throw new Error('대상(targeting)이 비어 있다 — allUsers / versionCodes / versionRange 중 하나는 필요하다.');
+    }
+    if (t.allUsers && (t.versionCodes?.length || t.versionRange)) {
+        throw new Error('allUsers 와 versionCodes/versionRange 는 함께 쓸 수 없다.');
+    }
+    return targeting;
+}
+export async function listRecoveryActions(auth, packageName, versionCode) {
+    const res = await publisher().apprecovery.list({
+        auth,
+        packageName,
+        ...(versionCode ? { versionCode } : {}),
+    });
+    return (res.data.recoveryActions ?? []).map((a) => ({
+        id: a.appRecoveryId,
+        status: a.status,
+        createTime: a.createTime,
+        deployTime: a.deployTime,
+        cancelTime: a.cancelTime,
+        targeting: a.targeting,
+    }));
+}
+/** DRAFT 상태로만 만든다 — 실제 배포는 deployRecoveryAction 이 별도로 한다. */
+export async function createRecoveryAction(auth, packageName, targeting) {
+    const res = await publisher().apprecovery.create({
+        auth,
+        packageName,
+        requestBody: {
+            remoteInAppUpdate: { isRemoteInAppUpdateRequested: true },
+            targeting: buildTargeting(targeting),
+        },
+    });
+    return {
+        id: res.data.appRecoveryId,
+        status: res.data.status,
+        targeting: res.data.targeting,
+    };
+}
+export async function deployRecoveryAction(auth, packageName, appRecoveryId) {
+    await publisher().apprecovery.deploy({
+        auth,
+        packageName,
+        appRecoveryId,
+        requestBody: {},
+    });
+    return { appRecoveryId, deployed: true };
+}
+export async function cancelRecoveryAction(auth, packageName, appRecoveryId) {
+    await publisher().apprecovery.cancel({
+        auth,
+        packageName,
+        appRecoveryId,
+        requestBody: {},
+    });
+    return { appRecoveryId, cancelled: true };
+}
 // ─── 데이터 안전(Safety Labels) 선언 ───
 //
 // 오랫동안 Console 전용이라고 알려졌지만 API 가 생겼다 (POST applications/{pkg}/dataSafety).

package/dist/registers/appstore.js

@@ -5,6 +5,8 @@ import * as appstoreProductReview from '../appstore/product-review.js';
 import * as appstoreProductLocalization from '../appstore/product-localization.js';
 import * as appstoreRelease from '../appstore/release.js';
 import * as appstoreDeclarations from '../appstore/declarations.js';
+import * as testflight from '../appstore/testflight.js';
+import * as previews from '../appstore/previews.js';
 import { createAppleOneTimePurchase, createAppleSubscription, updateAppleProduct, deleteAppleProduct, listAppleProducts, } from '@onesub/providers';
 import { requireAppStoreCreds } from '../helpers.js';
 import { buildAppStoreReleasePlan } from '../checks/plan.js';
@@ -1201,4 +1203,326 @@ export function registerAppstoreTools(server) {
                 }],
         };
     });
+    // ─── TestFlight 외부 테스트 ───
+    // 내부 테스터는 빌드 처리 후 바로 받지만, 외부 테스터는 Apple 베타 심사를 통과해야 한다.
+    // 심사에 필요한 항목이 앱 단위(심사 정보·테스트 정보)와 빌드 단위(What to Test)로 흩어져 있다.
+    server.tool('appstore_beta_status', [
+        'TestFlight 외부 테스트 제출 전 점검 — 읽기 전용. 빌드의 internal/external 상태,',
+        '베타 심사 제출 상태, What to Test 가 채워진 로케일을 보여준다.',
+        'appId 를 함께 주면 앱 단위 항목(베타 심사 연락처·데모 계정, 테스트 정보 로케일)까지 검사해 빠진 필드를 알려준다.',
+        '외부 배포가 막히면 여기부터 본다 — 대부분 수출 규정 미선언이나 심사 정보 공란이다.',
+    ].join(' '), {
+        buildId: z.string().describe('빌드 ID (appstore_list_builds 결과)'),
+        appId: z.string().optional().describe('앱 ID — 주면 앱 단위 항목까지 함께 점검'),
+    }, async ({ buildId, appId }) => {
+        const s = await testflight.getBetaStatus({ buildId, appId });
+        const lines = [
+            `빌드 ${buildId}`,
+            `  내부 상태: ${s.internalState ?? '?'}`,
+            `  외부 상태: ${s.externalState ?? '?'}${s.note ? ` — ${s.note}` : ''}`,
+            s.submissionState ? `  베타 심사 제출: ${s.submissionState}` : '  베타 심사 제출: 없음',
+            `  What to Test: ${s.whatsToTestLocales.length ? s.whatsToTestLocales.join(', ') : '❌ 비어 있음 (외부 배포 필수)'}`,
+            `  자동 알림: ${s.autoNotifyEnabled === undefined ? '?' : s.autoNotifyEnabled}`,
+        ];
+        if (s.reviewDetail) {
+            lines.push(s.reviewDetail.complete
+                ? '  베타 심사 정보: ✅ 채워짐'
+                : `  베타 심사 정보: ❌ 누락 — ${s.reviewDetail.missing.join(', ')}`);
+        }
+        if (s.testInfoLocales) {
+            lines.push(`  테스트 정보 로케일: ${s.testInfoLocales.length ? s.testInfoLocales.join(', ') : '❌ 없음'}`);
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    server.tool('appstore_update_beta_review_detail', [
+        'TestFlight 베타 심사 정보(연락처·데모 계정·심사 노트)를 채운다 — PATCH /v1/betaAppReviewDetails/{id}.',
+        '앱 단위 단일 리소스이며 외부 테스트 심사 제출 전 필수다. 넘긴 필드만 바뀐다.',
+        '로그인이 필요한 앱이면 demoAccountRequired=true 와 계정/비밀번호를 반드시 함께 넣는다 — 없으면 반려된다.',
+    ].join(' '), {
+        appId: z.string().describe('App Store 앱 ID'),
+        contactFirstName: z.string().optional().describe('심사 연락처 이름'),
+        contactLastName: z.string().optional().describe('심사 연락처 성'),
+        contactPhone: z.string().optional().describe('심사 연락처 전화번호'),
+        contactEmail: z.string().optional().describe('심사 연락처 이메일'),
+        demoAccountRequired: z.boolean().optional().describe('심사에 데모 계정이 필요한가'),
+        demoAccountName: z.string().optional().describe('데모 계정 ID'),
+        demoAccountPassword: z.string().optional().describe('데모 계정 비밀번호'),
+        notes: z.string().optional().describe('심사자에게 남길 메모'),
+    }, async ({ appId, ...fields }) => {
+        const r = await testflight.updateBetaReviewDetail({ appId, fields });
+        const changed = Object.keys(fields).filter((k) => fields[k] !== undefined);
+        return {
+            content: [{
+                    type: 'text',
+                    // 비밀번호는 값을 되읽어 출력하지 않는다 — 채워졌는지만 알린다.
+                    text: [`✅ 베타 심사 정보 갱신 (${r.id})`, ...changed.map((k) => k === 'demoAccountPassword' ? '  demoAccountPassword: (설정됨)' : `  ${k}: ${String(r.attributes[k] ?? '')}`)].join('\n'),
+                }],
+        };
+    });
+    server.tool('appstore_update_beta_test_info', [
+        'TestFlight 테스트 정보(피드백 이메일·앱 설명 등)를 로케일별로 저장한다 — betaAppLocalizations upsert.',
+        '해당 로케일이 있으면 PATCH, 없으면 POST 한다.',
+        '외부 테스트에는 feedbackEmail 과 description 이 필요하다.',
+    ].join(' '), {
+        appId: z.string().describe('App Store 앱 ID'),
+        locale: z.string().describe('로케일 (예: ko, en-US)'),
+        feedbackEmail: z.string().optional().describe('테스터 피드백 수신 이메일'),
+        description: z.string().optional().describe('테스터에게 보여줄 앱 설명'),
+        marketingUrl: z.string().optional().describe('마케팅 URL'),
+        privacyPolicyUrl: z.string().optional().describe('개인정보처리방침 URL'),
+    }, async ({ appId, locale, ...fields }) => {
+        const r = await testflight.upsertBetaTestInfo({ appId, locale, fields });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `✅ 테스트 정보 ${r.created ? '생성' : '수정'} — ${r.locale} (${r.id})`,
+                }],
+        };
+    });
+    server.tool('appstore_update_whats_to_test', [
+        '빌드의 What to Test 를 로케일별로 저장한다 — betaBuildLocalizations upsert.',
+        '외부 테스터 배포에는 필수다. 비어 있으면 베타 심사에서 막힌다.',
+        '버전 릴리스 노트(appstore_update_whats_new)와는 별개다 — 이건 TestFlight 전용이다.',
+    ].join(' '), {
+        buildId: z.string().describe('빌드 ID'),
+        locale: z.string().describe('로케일 (예: ko, en-US)'),
+        whatsNew: z.string().describe('이번 빌드에서 테스트할 내용'),
+    }, async ({ buildId, locale, whatsNew }) => {
+        const r = await testflight.upsertWhatsToTest({ buildId, locale, whatsNew });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `✅ What to Test ${r.created ? '생성' : '수정'} — ${r.locale} (${r.id})`,
+                }],
+        };
+    });
+    server.tool('appstore_submit_beta_review', [
+        '빌드를 TestFlight 베타 심사에 제출한다 — POST /v1/betaAppReviewSubmissions.',
+        '외부 테스터에게 배포하려면 이 심사를 통과해야 한다 (내부 테스터는 불필요).',
+        '사전 조건: 외부 상태가 READY_FOR_BETA_SUBMISSION, What to Test 채움, 베타 심사 정보 채움.',
+        'appstore_beta_status 로 먼저 점검할 것. confirm 생략/false 면 현재 상태만 보여주는 dry-run.',
+    ].join(' '), {
+        buildId: z.string().describe('빌드 ID'),
+        appId: z.string().optional().describe('앱 ID — dry-run 점검을 앱 단위 항목까지 확장'),
+        confirm: z.boolean().optional().describe('true 명시 시에만 실제 제출'),
+    }, async ({ buildId, appId, confirm }) => {
+        if (!confirm) {
+            const s = await testflight.getBetaStatus({ buildId, appId });
+            const blockers = [];
+            if (s.externalState !== 'READY_FOR_BETA_SUBMISSION') {
+                blockers.push(`외부 상태가 ${s.externalState ?? '?'} — ${s.note || '제출 가능 상태가 아니다'}`);
+            }
+            if (s.whatsToTestLocales.length === 0)
+                blockers.push('What to Test 가 비어 있다');
+            if (s.reviewDetail && !s.reviewDetail.complete) {
+                blockers.push(`베타 심사 정보 누락: ${s.reviewDetail.missing.join(', ')}`);
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            '🛑 베타 심사 제출 dry-run — 아직 제출하지 않았다.',
+                            `  빌드: ${buildId} (${s.externalState ?? '?'})`,
+                            blockers.length ? '  블로커:' : '  블로커 없음.',
+                            ...blockers.map((b) => `    - ${b}`),
+                            '',
+                            blockers.length ? '위 항목을 먼저 해결할 것.' : '제출하려면 confirm: true 로 다시 호출.',
+                        ].join('\n'),
+                    }],
+            };
+        }
+        const r = await testflight.submitBetaReview(buildId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        '✅ 베타 심사 제출',
+                        `  submissionId: ${r.submissionId}`,
+                        `  상태: ${r.state ?? '(응답에 없음)'}`,
+                        '진행 상황은 appstore_beta_status 로 확인.',
+                    ].join('\n'),
+                }],
+        };
+    });
+    server.tool('appstore_set_beta_group_build', [
+        '베타 그룹에 빌드를 붙이거나 뗀다 — POST/DELETE /v1/betaGroups/{id}/relationships/builds.',
+        '⚠️ 외부 그룹에 붙이는 것은 **실제 배포**다 (심사 통과 후에만 가능). 떼면 테스터가 더 이상 받지 못한다.',
+        'groupId 는 appstore_list_beta_groups 결과. confirm 생략/false 면 dry-run.',
+    ].join(' '), {
+        groupId: z.string().describe('베타 그룹 ID'),
+        buildId: z.string().describe('빌드 ID'),
+        action: z.enum(['add', 'remove']).describe('붙이기 / 떼기'),
+        confirm: z.boolean().optional().describe('true 명시 시에만 실행'),
+    }, async ({ groupId, buildId, action, confirm }) => {
+        if (!confirm) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            `🛑 dry-run — 아직 실행하지 않았다.`,
+                            `  그룹 ${groupId} ${action === 'add' ? '←' : '↛'} 빌드 ${buildId}`,
+                            action === 'add'
+                                ? '  외부 그룹이면 이 순간 테스터에게 배포된다.'
+                                : '  테스터는 이 빌드를 더 이상 설치할 수 없게 된다.',
+                            '',
+                            '실행하려면 confirm: true 로 다시 호출.',
+                        ].join('\n'),
+                    }],
+            };
+        }
+        const r = await testflight.setBetaGroupBuild({ groupId, buildId, action });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `✅ 그룹 ${r.groupId} ${r.action === 'add' ? '에 빌드 추가' : '에서 빌드 제거'} — ${r.buildId}`,
+                }],
+        };
+    });
+    server.tool('appstore_add_beta_testers', [
+        '베타 그룹에 테스터를 초대한다 — POST /v1/betaTesters.',
+        '이메일별로 개별 호출하며, 이미 등록된 주소는 실패로 표시하고 나머지는 계속 진행한다.',
+        '⚠️ 초대 메일이 즉시 발송된다 — 주소를 사용자에게 확인받고 실행할 것. confirm 필요.',
+    ].join(' '), {
+        groupId: z.string().describe('베타 그룹 ID (appstore_list_beta_groups 결과)'),
+        testers: z
+            .array(z.object({
+            email: z.string().describe('테스터 이메일'),
+            firstName: z.string().optional(),
+            lastName: z.string().optional(),
+        }))
+            .min(1)
+            .describe('초대할 테스터 목록'),
+        confirm: z.boolean().optional().describe('true 명시 시에만 초대 발송'),
+    }, async ({ groupId, testers, confirm }) => {
+        if (!confirm) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            `🛑 dry-run — ${testers.length}명, 아직 초대하지 않았다.`,
+                            ...testers.map((t) => `  ${t.email}`),
+                            '',
+                            '실행하려면 confirm: true 로 다시 호출. 초대 메일이 즉시 발송된다.',
+                        ].join('\n'),
+                    }],
+            };
+        }
+        const results = await testflight.addBetaTesters({ groupId, testers });
+        const ok = results.filter((r) => r.ok).length;
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `테스터 초대: 성공 ${ok} / 실패 ${results.length - ok}`,
+                        ...results.filter((r) => !r.ok).map((r) => `  ✗ ${r.email}: ${r.error}`),
+                    ].join('\n'),
+                }],
+        };
+    });
+    server.tool('appstore_notify_beta_testers', [
+        '이미 배포된 빌드에 대해 테스터에게 알림을 다시 보낸다 — POST /v1/buildBetaNotifications.',
+        '자동 알림(autoNotifyEnabled)이 꺼져 있거나, 배포 후 다시 알리고 싶을 때.',
+        '⚠️ 테스터 전원에게 푸시/메일이 나간다. confirm 필요.',
+    ].join(' '), {
+        buildId: z.string().describe('빌드 ID'),
+        confirm: z.boolean().optional().describe('true 명시 시에만 발송'),
+    }, async ({ buildId, confirm }) => {
+        if (!confirm) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `🛑 dry-run — 빌드 ${buildId} 의 테스터 전원에게 알림을 보낼 참이다. confirm: true 로 다시 호출.`,
+                    }],
+            };
+        }
+        const r = await testflight.notifyBetaTesters(buildId);
+        return { content: [{ type: 'text', text: `✅ 알림 발송 (${r.notificationId})` }] };
+    });
+    // ─── 제품 페이지 미리보기 동영상 ───
+    // 스크린샷과 같은 4단계 업로드지만, 커밋 후 Apple 인코딩이 남는다 — 업로드 성공 ≠ 노출 가능.
+    const PREVIEW_TYPES = [
+        'IPHONE_67', 'IPHONE_61', 'IPHONE_65', 'IPHONE_58', 'IPHONE_55', 'IPHONE_47', 'IPHONE_40', 'IPHONE_35',
+        'IPAD_PRO_3GEN_129', 'IPAD_PRO_3GEN_11', 'IPAD_PRO_129', 'IPAD_105', 'IPAD_97',
+        'DESKTOP', 'APPLE_TV', 'APPLE_VISION_PRO',
+    ];
+    server.tool('appstore_list_previews', [
+        '버전 로케일의 미리보기 동영상 세트를 조회한다 — 읽기 전용.',
+        '세트별 previewType 과 각 동영상의 처리 상태(assetDeliveryState)·포스터 프레임·videoUrl 을 보여준다.',
+        '업로드 직후 인코딩이 끝났는지 확인할 때도 이걸 쓴다.',
+    ].join(' '), {
+        localizationId: z
+            .string()
+            .describe('appStoreVersionLocalization ID (appstore_get_metadata 결과의 로케일별 id)'),
+    }, async ({ localizationId }) => {
+        const sets = await previews.listPreviewSets(localizationId);
+        if (sets.length === 0) {
+            return { content: [{ type: 'text', text: '미리보기 세트 없음.' }] };
+        }
+        const lines = [];
+        for (const s of sets) {
+            lines.push(`${s.previewType ?? '?'} (set ${s.id}) — ${s.previews.length}개`);
+            for (const p of s.previews) {
+                lines.push(`  ${p.id}: ${p.fileName ?? '?'} · ${p.state ?? '상태 미상'}` +
+                    (p.previewFrameTimeCode ? ` · 포스터 ${p.previewFrameTimeCode}` : '') +
+                    (p.videoUrl ? ' · 재생 가능' : ''));
+            }
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    server.tool('appstore_upload_preview', [
+        '제품 페이지 미리보기 **동영상**을 업로드한다 — appPreviewSets/appPreviews 4단계 업로드.',
+        'previewType 세트가 없으면 만들고, 예약 → 조각 업로드 → 커밋까지 한 번에 처리한다.',
+        '⚠️ 커밋 후 Apple 인코딩이 남는다 — 성공 응답이 곧 노출 가능은 아니다. appstore_list_previews 로 확인할 것.',
+        'Apple 제약: 길이 15~30초, previewType 별 해상도 고정, 로케일·타입당 최대 3개. 어기면 인코딩 단계에서 거부된다.',
+        'previewFrameTimeCode(HH:MM:SS:FF)로 포스터 프레임을 지정할 수 있다.',
+        '파일은 절대경로로 넘긴다 (대용량이라 조각 업로드하며, 동영상 바이트는 대화에 싣지 않는다).',
+    ].join(' '), {
+        localizationId: z.string().describe('appStoreVersionLocalization ID'),
+        previewType: z.enum(PREVIEW_TYPES).describe('미리보기 타입 (기기군)'),
+        filePath: z.string().describe('동영상 파일 절대경로 (.mp4 / .mov / .m4v)'),
+        previewFrameTimeCode: z
+            .string()
+            .optional()
+            .describe('포스터 프레임 시각 HH:MM:SS:FF (예: 00:00:03:00)'),
+    }, async ({ localizationId, previewType, filePath, previewFrameTimeCode }) => {
+        const r = await previews.uploadPreview({ localizationId, previewType, filePath, previewFrameTimeCode });
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        '✅ 미리보기 업로드 완료 (인코딩 대기)',
+                        `  id: ${r.id}`,
+                        `  파일: ${r.fileName} (${(r.fileSize / 1024 / 1024).toFixed(1)} MB)`,
+                        `  타입: ${r.previewType}`,
+                        `  상태: ${r.state ?? '처리 중'}`,
+                        'Apple 인코딩이 끝나야 노출된다 — appstore_list_previews 로 상태를 확인할 것.',
+                    ].join('\n'),
+                }],
+        };
+    });
+    server.tool('appstore_delete_preview', [
+        '미리보기 동영상 또는 세트를 삭제한다 — DELETE /v1/appPreviews/{id} 또는 /appPreviewSets/{id}.',
+        '⚠️ 되돌릴 수 없다. 세트를 지우면 그 안의 동영상이 모두 사라진다. confirm 필요.',
+    ].join(' '), {
+        previewId: z.string().optional().describe('삭제할 미리보기 ID (set 과 둘 중 하나)'),
+        setId: z.string().optional().describe('삭제할 미리보기 세트 ID (안의 동영상 전부 삭제)'),
+        confirm: z.boolean().optional().describe('true 명시 시에만 삭제'),
+    }, async ({ previewId, setId, confirm }) => {
+        if (!previewId && !setId)
+            throw new Error('previewId 또는 setId 중 하나는 필요하다.');
+        if (!confirm) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: previewId
+                            ? `🛑 dry-run — 미리보기 ${previewId} 를 삭제할 참이다. confirm: true 로 다시 호출.`
+                            : `🛑 dry-run — 세트 ${setId} 와 그 안의 동영상 전부를 삭제할 참이다. confirm: true 로 다시 호출.`,
+                    }],
+            };
+        }
+        const r = previewId
+            ? await previews.deletePreview(previewId)
+            : await previews.deletePreviewSet(setId);
+        return { content: [{ type: 'text', text: `✅ 삭제 완료 — ${r.id}` }] };
+    });
 }

package/dist/registers/playstore.js

@@ -809,4 +809,127 @@ export function registerPlaystoreTools(server) {
                 }],
         };
     });
+    // ─── 앱 복구 (출시 후 긴급 대응) ───
+    server.tool('playstore_list_recovery_actions', [
+        '앱 복구 액션 목록을 조회한다 — 읽기 전용 (apprecovery.list).',
+        '이미 배포된 앱이 치명적으로 망가졌을 때 특정 버전 사용자에게 원격 인앱 업데이트를 밀어 넣는 장치다.',
+        '상태(DRAFT/ACTIVE/CANCELED)·생성·배포·취소 시각과 대상을 보여준다.',
+    ].join(' '), {
+        packageName: z.string().describe('패키지명'),
+        versionCode: z.string().optional().describe('특정 버전 코드로 필터'),
+    }, async ({ packageName, versionCode }) => {
+        const auth = await requirePlayStoreAuth(packageName);
+        const rows = await playstore.listRecoveryActions(auth, packageName, versionCode);
+        if (rows.length === 0)
+            return { content: [{ type: 'text', text: '복구 액션 없음.' }] };
+        return {
+            content: [{
+                    type: 'text',
+                    text: rows
+                        .map((r) => [
+                        `${r.id}: ${r.status}`,
+                        r.createTime ? `  생성 ${r.createTime}` : '',
+                        r.deployTime ? `  배포 ${r.deployTime}` : '',
+                        r.cancelTime ? `  취소 ${r.cancelTime}` : '',
+                        `  대상: ${JSON.stringify(r.targeting ?? {})}`,
+                    ].filter(Boolean).join('\n'))
+                        .join('\n'),
+                }],
+        };
+    });
+    server.tool('playstore_create_recovery_action', [
+        '앱 복구 액션을 DRAFT 상태로 만든다 — apprecovery.create.',
+        '만들기만 하고 배포하지 않는다 (배포는 playstore_deploy_recovery_action).',
+        '대상은 allUsers 또는 versionCodes / versionRange 중 하나로 정한다 — allUsers 와 버전 지정은 함께 못 쓴다.',
+        '⚠️ 배포 후에는 대상을 만들 때 고른 기준 안에서만 넓힐 수 있다. 범위를 신중히 잡을 것.',
+        '이건 롤백이 아니라 "고친 버전으로 강제 업데이트"다 — 먼저 정상 빌드를 올려 둬야 의미가 있다.',
+    ].join(' '), {
+        packageName: z.string().describe('패키지명'),
+        allUsers: z.boolean().optional().describe('전체 사용자 대상 (버전 지정과 함께 쓸 수 없음)'),
+        versionCodes: z.array(z.string()).optional().describe('대상 버전 코드 목록'),
+        versionRangeStart: z.string().optional().describe('대상 버전 범위 시작'),
+        versionRangeEnd: z.string().optional().describe('대상 버전 범위 끝'),
+        regions: z.array(z.string()).optional().describe('지역 코드 (예: KR, US)'),
+        sdkLevels: z.array(z.string()).optional().describe('Android SDK 레벨'),
+        confirm: z.boolean().optional().describe('true 명시 시에만 생성. 생략/false 면 계획만 반환.'),
+    }, async ({ packageName, allUsers, versionCodes, versionRangeStart, versionRangeEnd, regions, sdkLevels, confirm }) => {
+        const targeting = {
+            allUsers,
+            versionCodes,
+            versionRange: versionRangeStart && versionRangeEnd
+                ? { start: versionRangeStart, end: versionRangeEnd }
+                : undefined,
+            regions,
+            sdkLevels,
+        };
+        if (!confirm) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            '🛑 dry-run — 아직 만들지 않았다.',
+                            `  패키지: ${packageName}`,
+                            `  대상: ${JSON.stringify(targeting)}`,
+                            '',
+                            'DRAFT 로 만들려면 confirm: true. 만든 뒤에도 배포는 별도 단계다.',
+                        ].join('\n'),
+                    }],
+            };
+        }
+        const auth = await requirePlayStoreAuth(packageName);
+        const r = await playstore.createRecoveryAction(auth, packageName, targeting);
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        '✅ 복구 액션 생성 (DRAFT — 아직 사용자에게 나가지 않았다)',
+                        `  id: ${r.id}`,
+                        `  상태: ${r.status}`,
+                        '배포하려면 playstore_deploy_recovery_action.',
+                    ].join('\n'),
+                }],
+        };
+    });
+    server.tool('playstore_deploy_recovery_action', [
+        'DRAFT 복구 액션을 실제로 배포한다 — apprecovery.deploy.',
+        '⚠️ 대상 사용자 기기에 원격 인앱 업데이트가 나간다. 되돌리려면 취소해야 하고, 이미 적용된 기기는 되돌아가지 않는다.',
+        '배포 전 playstore_list_recovery_actions 로 대상 범위를 반드시 재확인할 것. confirm 필요.',
+    ].join(' '), {
+        packageName: z.string().describe('패키지명'),
+        appRecoveryId: z.string().describe('복구 액션 ID'),
+        confirm: z.boolean().optional().describe('true 명시 시에만 배포'),
+    }, async ({ packageName, appRecoveryId, confirm }) => {
+        if (!confirm) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `🛑 dry-run — 복구 액션 ${appRecoveryId} 를 배포할 참이다. 대상 사용자에게 원격 업데이트가 나간다. confirm: true 로 다시 호출.`,
+                    }],
+            };
+        }
+        const auth = await requirePlayStoreAuth(packageName);
+        const r = await playstore.deployRecoveryAction(auth, packageName, appRecoveryId);
+        return { content: [{ type: 'text', text: `✅ 복구 액션 배포 — ${r.appRecoveryId}` }] };
+    });
+    server.tool('playstore_cancel_recovery_action', [
+        '진행 중인 복구 액션을 취소한다 — apprecovery.cancel.',
+        '아직 받지 않은 기기에는 더 이상 나가지 않는다. 이미 적용된 기기는 되돌아가지 않는다.',
+        'confirm 필요.',
+    ].join(' '), {
+        packageName: z.string().describe('패키지명'),
+        appRecoveryId: z.string().describe('복구 액션 ID'),
+        confirm: z.boolean().optional().describe('true 명시 시에만 취소'),
+    }, async ({ packageName, appRecoveryId, confirm }) => {
+        if (!confirm) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `🛑 dry-run — 복구 액션 ${appRecoveryId} 를 취소할 참이다. 이미 적용된 기기는 되돌아가지 않는다. confirm: true 로 다시 호출.`,
+                    }],
+            };
+        }
+        const auth = await requirePlayStoreAuth(packageName);
+        const r = await playstore.cancelRecoveryAction(auth, packageName, appRecoveryId);
+        return { content: [{ type: 'text', text: `✅ 복구 액션 취소 — ${r.appRecoveryId}` }] };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoonion/mimi-seed-mcp",
-  "version": "0.13.16",
+  "version": "0.13.18",
   "description": "Mimi Seed MCP server — Firebase + AdMob + Google Play + App Store management for Claude Code / Codex / Cursor / any MCP client.",
   "type": "module",
   "bin": {

package/tool-manifest.json

@@ -1,6 +1,6 @@
 {
   "$comment": "등록된 MCP 도구 + 도메인 메타데이터(label·credential·summary)의 SSOT. src/__tests__/tool-manifest.test.ts 가 실제 서버 등록 목록과 diff 하고 메타데이터 정합성을 검사한다. 도구 추가/삭제/개명 시 이 파일을 함께 갱신할 것 — 산문 문서에는 정확한 개수를 쓰지 말고 이 파일을 가리킬 것. mimi-seed://tools/catalog 리소스가 이 파일을 그대로 서빙한다.",
-  "total": 199,
+  "total": 214,
   "domains": {
     "admob": {
       "label": "AdMob",
@@ -89,7 +89,18 @@
         "appstore_update_age_rating",
         "appstore_declare_encryption",
         "appstore_get_availability",
-        "appstore_set_territory_availability"
+        "appstore_set_territory_availability",
+        "appstore_beta_status",
+        "appstore_update_beta_review_detail",
+        "appstore_update_beta_test_info",
+        "appstore_update_whats_to_test",
+        "appstore_submit_beta_review",
+        "appstore_set_beta_group_build",
+        "appstore_add_beta_testers",
+        "appstore_notify_beta_testers",
+        "appstore_list_previews",
+        "appstore_upload_preview",
+        "appstore_delete_preview"
       ]
     },
     "auth": {
@@ -297,7 +308,11 @@
         "playstore_update_product",
         "playstore_delete_product",
         "setup_playstore_connection",
-        "playstore_upload_data_safety"
+        "playstore_upload_data_safety",
+        "playstore_list_recovery_actions",
+        "playstore_create_recovery_action",
+        "playstore_deploy_recovery_action",
+        "playstore_cancel_recovery_action"
       ]
     },
     "threads": {