@yoonion/mimi-seed-mcp 0.13.15 → 0.13.17

package/README.md

@@ -78,8 +78,8 @@ export ANTHROPIC_API_KEY=sk-ant-...
 
 | 영역 | 도구 수 | 주요 도구 |
 |------|---------|-----------|
-| App Store Connect | 41 | `appstore_submit_for_review` / `appstore_upload_screenshot` / `appstore_update_product_review_note` / `appstore_upload_product_review_screenshot` |
-| Google Play | 32 | `playstore_submit_release` / `playstore_promote_release` / `playstore_replace_images` / `playstore_reply_review` / `playstore_verify_service_account` |
+| App Store Connect | 58 | `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` |
 | 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

@@ -54,6 +54,9 @@ you can paste. Pick the row for the job; batching two rows in one `select:` call
 | Play Store reviews + stats | `select:playstore_list_reviews,playstore_reply_review,playstore_get_statistics,generate_review_reply` |
 | Play Store IAP / subscriptions | `select:playstore_list_products,playstore_list_inapp_products,playstore_list_subscriptions,playstore_create_onetime_product,playstore_create_subscription,playstore_update_product,playstore_update_product_listing,playstore_update_subscription_listing,playstore_update_product_state,playstore_delete_product` |
 | 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 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` |
@@ -249,9 +252,9 @@ General rules:
 - **Draft-app track constraint (Play).** Until an app has its first non-internal
   publish, only the **`internal`** track can be `completed`. `alpha`/`beta`/`production`
   reject anything but `draft` → error: *"Only releases with status draft may be created
-  on draft app."* Closed/open testing also needs the **App Content** declarations
-  (content rating, data safety, target audience) which are **Console-only** — the API
-  cannot set them.
+  on draft app."* Closed/open testing also needs the **App Content** declarations. **Data safety** is
+  uploadable as a CSV (`playstore_upload_data_safety`); **content rating and target
+  audience remain Console-only** — no API sets them.
 - **A `403` on one write but not another is usually NOT a permissions gap.** Every
   `playstore_*` write resolves the same credential (`requirePlayStoreAuth`), so if
   `playstore_upload_image` succeeds but `playstore_update_listing` returns `403`, the

package/dist/appstore/declarations.d.ts

@@ -0,0 +1,73 @@
+/** Apple 이 쓰는 빈도 척도. 필드마다 같은 enum 을 쓴다. */
+export type Frequency = 'NONE' | 'INFREQUENT_OR_MILD' | 'FREQUENT_OR_INTENSE' | 'INFREQUENT' | 'FREQUENT';
+export interface AgeRatingDeclaration {
+    [key: string]: string | boolean | undefined;
+}
+export declare function getAgeRating(appId: string): Promise<{
+    appInfoId: string;
+    declarationId?: string;
+    declaration: AgeRatingDeclaration;
+}>;
+/**
+ * 연령 등급 설문 갱신 (PATCH /v1/ageRatingDeclarations/{id}).
+ * 넘긴 필드만 바뀐다 — Apple 이 부분 갱신을 허용하므로 전체를 다시 보낼 필요가 없다.
+ */
+export declare function updateAgeRating(args: {
+    appId: string;
+    declaration: AgeRatingDeclaration;
+}): Promise<{
+    declarationId: string;
+    declaration: AgeRatingDeclaration;
+}>;
+/**
+ * 수출 규정 선언 생성 (POST /v1/appEncryptionDeclarations).
+ * buildIds 를 주면 그 빌드들에 바로 연결한다 (POST …/relationships/builds).
+ *
+ * Info.plist 의 ITSAppUsesNonExemptEncryption 으로 해결되는 경우가 더 많다 —
+ * 이 도구는 그게 없어서 ASC 가 선언을 요구할 때의 경로다.
+ */
+export declare function declareEncryption(args: {
+    appId: string;
+    appDescription: string;
+    containsProprietaryCryptography: boolean;
+    containsThirdPartyCryptography: boolean;
+    availableOnFrenchStore: boolean;
+    buildIds?: string[];
+}): Promise<{
+    declarationId: string;
+    state?: string;
+    attachedBuilds: number;
+}>;
+export interface TerritoryRow {
+    /** territoryAvailability 리소스 id — PATCH 할 때 그대로 쓴다. */
+    id: string;
+    available?: boolean;
+    releaseDate?: string;
+    preOrderEnabled?: boolean;
+}
+/**
+ * 현재 판매 지역 상태 (GET /v1/apps/{id}/appAvailabilityV2 → territoryAvailabilities).
+ * 지역이 175개라 기본은 판매 중인 곳만 세고, `includeTerritories` 로 목록을 받는다.
+ */
+export declare function getAvailability(args: {
+    appId: string;
+    includeTerritories?: boolean;
+    limit?: number;
+}): Promise<{
+    availabilityId?: string;
+    availableInNewTerritories?: boolean;
+    availableCount: number;
+    unavailableCount: number;
+    territories?: TerritoryRow[];
+}>;
+/**
+ * 지역별 판매 여부·출시일 변경 (PATCH /v1/territoryAvailabilities/{id}).
+ * id 는 appstore_get_availability 결과에서 온다 — 추측해서 만들지 말 것.
+ */
+export declare function setTerritoryAvailability(args: {
+    territories: TerritoryRow[];
+}): Promise<Array<{
+    id: string;
+    ok: boolean;
+    error?: string;
+}>>;

package/dist/appstore/declarations.js

@@ -0,0 +1,163 @@
+// 심사 제출 **전에** 채워야 하는 선언들 — 비어 있으면 제출 자체가 막히거나 심사에서 반려된다.
+//
+//   연령 등급 (ageRatingDeclarations)        : appInfo 에 딸린 단일 리소스. PATCH 로만 바꾼다
+//   수출 규정 (appEncryptionDeclarations)    : 앱 단위로 만들고 빌드에 붙인다
+//   판매 지역 (appAvailabilityV2 / territoryAvailabilities): 지역별 available·출시일
+//
+// Play 쪽 대응물(데이터 안전 CSV)은 playstore/tools.ts 에 있다 — 자격증명 계통이 달라서 파일을 나눴다.
+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()}` : '';
+    return apiRequest(base, `${path}${query}`, headers, { method: 'GET' });
+}
+async function send(base, method, path, body) {
+    const headers = await authHeadersOrThrow();
+    return apiRequest(base, path, headers, {
+        method,
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+}
+/** 연령 등급은 appInfo 에 딸려 있다. 편집 가능한 appInfo 를 우선 고른다. */
+async function resolveAppInfoId(appId) {
+    const data = await get(V1_BASE, `/apps/${appId}/appInfos`, { 'fields[appInfos]': 'state' });
+    const infos = data.data ?? [];
+    if (infos.length === 0)
+        throw new Error(`앱 ${appId} 의 appInfo 를 찾지 못했다.`);
+    const editable = infos.find((i) => {
+        const s = i.attributes?.state ?? i.attributes?.appStoreState;
+        return s && s !== 'READY_FOR_DISTRIBUTION' && s !== 'REPLACED_WITH_NEW_INFO';
+    });
+    return (editable ?? infos[0]).id;
+}
+export async function getAgeRating(appId) {
+    const appInfoId = await resolveAppInfoId(appId);
+    // 선언 리소스가 아직 없는 앱이 있다 — 그때는 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}).
+ * 넘긴 필드만 바뀐다 — Apple 이 부분 갱신을 허용하므로 전체를 다시 보낼 필요가 없다.
+ */
+export async function updateAgeRating(args) {
+    const { appId, declaration } = args;
+    const attributes = Object.fromEntries(Object.entries(declaration).filter(([, v]) => v !== undefined));
+    if (Object.keys(attributes).length === 0) {
+        throw new Error('바꿀 항목이 하나도 없다 — declaration 에 최소 한 필드는 넣어야 한다.');
+    }
+    const current = await getAgeRating(appId);
+    if (!current.declarationId) {
+        throw new Error([
+            '❌ 이 앱에는 연령 등급 선언 리소스가 없다.',
+            'App Store Connect 에서 앱을 한 번 연 뒤 다시 시도하거나, appInfo 상태를 확인할 것.',
+        ].join('\n'));
+    }
+    await send(V1_BASE, 'PATCH', `/ageRatingDeclarations/${current.declarationId}`, {
+        data: { type: 'ageRatingDeclarations', id: current.declarationId, attributes },
+    });
+    const after = await getAgeRating(appId);
+    return { declarationId: current.declarationId, declaration: after.declaration };
+}
+/**
+ * 수출 규정 선언 생성 (POST /v1/appEncryptionDeclarations).
+ * buildIds 를 주면 그 빌드들에 바로 연결한다 (POST …/relationships/builds).
+ *
+ * Info.plist 의 ITSAppUsesNonExemptEncryption 으로 해결되는 경우가 더 많다 —
+ * 이 도구는 그게 없어서 ASC 가 선언을 요구할 때의 경로다.
+ */
+export async function declareEncryption(args) {
+    const { appId, buildIds = [], ...attributes } = args;
+    const created = await send(V1_BASE, 'POST', '/appEncryptionDeclarations', {
+        data: {
+            type: 'appEncryptionDeclarations',
+            attributes,
+            relationships: { app: { data: { type: 'apps', id: appId } } },
+        },
+    });
+    const declarationId = created.data?.id;
+    if (!declarationId)
+        throw new Error(`수출 규정 선언 생성 응답에 id 가 없다: ${JSON.stringify(created)}`);
+    if (buildIds.length > 0) {
+        await send(V1_BASE, 'POST', `/appEncryptionDeclarations/${declarationId}/relationships/builds`, {
+            data: buildIds.map((id) => ({ type: 'builds', id })),
+        });
+    }
+    return {
+        declarationId,
+        state: created.data?.attributes?.state,
+        attachedBuilds: buildIds.length,
+    };
+}
+/**
+ * 현재 판매 지역 상태 (GET /v1/apps/{id}/appAvailabilityV2 → territoryAvailabilities).
+ * 지역이 175개라 기본은 판매 중인 곳만 세고, `includeTerritories` 로 목록을 받는다.
+ */
+export async function getAvailability(args) {
+    const { appId, includeTerritories = false, limit = 200 } = args;
+    const av = await get(V1_BASE, `/apps/${appId}/appAvailabilityV2`);
+    const availabilityId = av.data?.id;
+    if (!availabilityId) {
+        return { availableCount: 0, unavailableCount: 0, availableInNewTerritories: undefined };
+    }
+    const rows = await get(V2_BASE, `/appAvailabilities/${availabilityId}/territoryAvailabilities`, {
+        limit: String(Math.min(limit, 200)),
+    });
+    const list = (rows.data ?? []).map((t) => ({
+        id: t.id,
+        available: t.attributes?.available,
+        releaseDate: t.attributes?.releaseDate,
+        preOrderEnabled: t.attributes?.preOrderEnabled,
+    }));
+    return {
+        availabilityId,
+        availableInNewTerritories: av.data?.attributes?.availableInNewTerritories,
+        availableCount: list.filter((t) => t.available).length,
+        unavailableCount: list.filter((t) => t.available === false).length,
+        ...(includeTerritories ? { territories: list } : {}),
+    };
+}
+/**
+ * 지역별 판매 여부·출시일 변경 (PATCH /v1/territoryAvailabilities/{id}).
+ * id 는 appstore_get_availability 결과에서 온다 — 추측해서 만들지 말 것.
+ */
+export async function setTerritoryAvailability(args) {
+    const results = [];
+    for (const t of args.territories) {
+        const attributes = {};
+        if (t.available !== undefined)
+            attributes.available = t.available;
+        if (t.releaseDate !== undefined)
+            attributes.releaseDate = t.releaseDate;
+        if (t.preOrderEnabled !== undefined)
+            attributes.preOrderEnabled = t.preOrderEnabled;
+        if (Object.keys(attributes).length === 0) {
+            results.push({ id: t.id, ok: false, error: '바꿀 필드가 없음' });
+            continue;
+        }
+        try {
+            await send(V1_BASE, 'PATCH', `/territoryAvailabilities/${t.id}`, {
+                data: { type: 'territoryAvailabilities', id: t.id, attributes },
+            });
+            results.push({ id: t.id, ok: true });
+        }
+        catch (err) {
+            // 한 지역 실패가 나머지를 막지 않게 한다 — 어디까지 됐는지 그대로 보고한다.
+            results.push({ id: t.id, ok: false, error: err.message });
+        }
+    }
+    return results;
+}

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/release.d.ts

@@ -0,0 +1,58 @@
+export type AppleReleaseType = 'MANUAL' | 'AFTER_APPROVAL' | 'SCHEDULED';
+export type PhasedReleaseState = 'INACTIVE' | 'ACTIVE' | 'PAUSED' | 'COMPLETE';
+export type PhasedReleaseAction = 'status' | 'enable' | 'pause' | 'resume' | 'complete' | 'disable';
+export interface VersionReleaseSummary {
+    versionId: string;
+    versionString?: string;
+    state?: string;
+    releaseType?: string;
+    earliestReleaseDate?: string;
+}
+export interface PhasedReleaseSummary {
+    id: string;
+    state?: PhasedReleaseState;
+    /** 1~7. Apple 의 7일 램프에서 현재 며칠째인지. */
+    currentDayNumber?: number;
+    startDate?: string;
+    totalPauseDuration?: number;
+}
+export declare function getVersionSummary(versionId: string): Promise<VersionReleaseSummary>;
+export declare function stateNote(state?: string): string;
+/** 버전 상태 + 단계적 출시 상태를 한 번에. 쓰기 전 미리보기용. */
+export declare function getReleaseStatus(versionId: string): Promise<{
+    version: VersionReleaseSummary;
+    phased: PhasedReleaseSummary | null;
+    note: string;
+}>;
+/**
+ * 개발자 출시 대기 중인 버전을 지금 출시한다 (POST /v1/appStoreVersionReleaseRequests).
+ * 콘솔의 "이 버전 출시" 버튼과 같은 동작 — 되돌릴 수 없다.
+ */
+export declare function requestRelease(versionId: string): Promise<VersionReleaseSummary>;
+/**
+ * 이미 만들어진 버전의 출시 방식을 바꾼다 (PATCH /v1/appStoreVersions/{id}).
+ * MANUAL 로 만들어 두고 "역시 승인되면 바로 내보내자"로 바꾸는 경우가 대부분.
+ * SCHEDULED 는 earliestReleaseDate(ISO 8601, 미래)가 함께 필요하다.
+ */
+export declare function updateReleaseType(args: {
+    versionId: string;
+    releaseType: AppleReleaseType;
+    earliestReleaseDate?: string;
+}): Promise<VersionReleaseSummary>;
+/**
+ * 단계적 출시(7일 램프) 제어.
+ *
+ * - enable   : 없으면 만들고(ACTIVE), PAUSED 면 재개한다
+ * - pause    : 일시중지 (되돌릴 수 있음)
+ * - resume   : 재개
+ * - complete : 남은 사용자에게 즉시 전체 공개 — 되돌릴 수 없다
+ * - disable  : 단계적 출시 자체를 제거. 출시 전이면 일반(전체) 출시로, 출시 후면 즉시 전체 공개가 된다
+ */
+export declare function setPhasedRelease(args: {
+    versionId: string;
+    action: Exclude<PhasedReleaseAction, 'status'>;
+}): Promise<{
+    action: string;
+    phased: PhasedReleaseSummary | null;
+    version: VersionReleaseSummary;
+}>;

package/dist/appstore/release.js

@@ -0,0 +1,173 @@
+// App Store 출시 제어 — 심사 통과 **이후**의 단계.
+//
+// 버전 생성 때 releaseType 을 정하는 것(appstore_create_version)까지는 이미 되지만,
+// 그 뒤 세 가지가 API 로 안 됐다:
+//   1. 이미 PENDING_DEVELOPER_RELEASE 로 대기 중인 버전을 "지금 출시" (releaseRequests)
+//   2. 만들어 둔 버전의 releaseType 을 나중에 바꾸기 (PATCH appStoreVersions)
+//   3. 단계적 출시 시작·일시중지·재개·즉시완료 (phasedRelease)
+// Play 는 userFraction/halted 로 3번이 되는데 iOS 만 비어 있었다.
+import { V1_BASE, apiRequest, authHeadersOrThrow, isNotFound } from './http.js';
+/** 각 상태가 "지금 출시" 요청을 받을 수 있는지 + 사람이 읽을 설명. */
+const STATE_NOTE = {
+    PENDING_DEVELOPER_RELEASE: '심사 통과 후 개발자 출시 대기 — 지금 출시할 수 있다.',
+    PENDING_APPLE_RELEASE: '예약 출시 대기 — Apple 이 earliestReleaseDate 에 출시한다.',
+    READY_FOR_SALE: '이미 출시됨.',
+    WAITING_FOR_REVIEW: '심사 대기열에 있음.',
+    IN_REVIEW: '심사 진행 중.',
+    PREPARE_FOR_SUBMISSION: '아직 제출 전 — appstore_submit_for_review 먼저.',
+    DEVELOPER_REJECTED: '개발자가 회수함 — 다시 제출해야 한다.',
+    REJECTED: 'Apple 이 거절함 — 수정 후 재제출.',
+    METADATA_REJECTED: '메타데이터 거절 — 수정 후 재제출.',
+};
+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) }),
+    });
+}
+export async function getVersionSummary(versionId) {
+    const data = await get(`/appStoreVersions/${versionId}`, { 'fields[appStoreVersions]': 'versionString,appStoreState,releaseType,earliestReleaseDate' });
+    const a = data.data?.attributes ?? {};
+    return {
+        versionId,
+        versionString: a.versionString,
+        state: a.appStoreState,
+        releaseType: a.releaseType,
+        earliestReleaseDate: a.earliestReleaseDate,
+    };
+}
+/** to-one 관계는 없을 때 200 + data:null 로 오기도 하고 404 로 오기도 한다. 둘 다 "없음"으로 본다. */
+async function getPhasedRelease(versionId) {
+    try {
+        const data = await get(`/appStoreVersions/${versionId}/appStoreVersionPhasedRelease`);
+        if (!data.data)
+            return null;
+        const a = (data.data.attributes ?? {});
+        return {
+            id: data.data.id,
+            state: a.phasedReleaseState,
+            currentDayNumber: a.currentDayNumber,
+            startDate: a.startDate,
+            totalPauseDuration: a.totalPauseDuration,
+        };
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return null;
+        throw err;
+    }
+}
+export function stateNote(state) {
+    return (state && STATE_NOTE[state]) || '';
+}
+/** 버전 상태 + 단계적 출시 상태를 한 번에. 쓰기 전 미리보기용. */
+export async function getReleaseStatus(versionId) {
+    const version = await getVersionSummary(versionId);
+    const phased = await getPhasedRelease(versionId);
+    return { version, phased, note: stateNote(version.state) };
+}
+/**
+ * 개발자 출시 대기 중인 버전을 지금 출시한다 (POST /v1/appStoreVersionReleaseRequests).
+ * 콘솔의 "이 버전 출시" 버튼과 같은 동작 — 되돌릴 수 없다.
+ */
+export async function requestRelease(versionId) {
+    const version = await getVersionSummary(versionId);
+    if (version.state !== 'PENDING_DEVELOPER_RELEASE') {
+        throw new Error([
+            `❌ 지금 출시할 수 없는 상태다: ${version.state ?? '(알 수 없음)'}`,
+            stateNote(version.state),
+            '',
+            '출시 요청은 심사를 통과해 PENDING_DEVELOPER_RELEASE 로 대기 중인 버전에만 보낼 수 있다.',
+        ]
+            .filter(Boolean)
+            .join('\n'));
+    }
+    await send('POST', '/appStoreVersionReleaseRequests', {
+        data: {
+            type: 'appStoreVersionReleaseRequests',
+            relationships: { appStoreVersion: { data: { type: 'appStoreVersions', id: versionId } } },
+        },
+    });
+    return getVersionSummary(versionId);
+}
+/**
+ * 이미 만들어진 버전의 출시 방식을 바꾼다 (PATCH /v1/appStoreVersions/{id}).
+ * MANUAL 로 만들어 두고 "역시 승인되면 바로 내보내자"로 바꾸는 경우가 대부분.
+ * SCHEDULED 는 earliestReleaseDate(ISO 8601, 미래)가 함께 필요하다.
+ */
+export async function updateReleaseType(args) {
+    const { versionId, releaseType, earliestReleaseDate } = args;
+    if (releaseType === 'SCHEDULED' && !earliestReleaseDate) {
+        throw new Error('releaseType=SCHEDULED 에는 earliestReleaseDate(ISO 8601, 미래 시각)가 필요하다.');
+    }
+    const attributes = { releaseType };
+    // SCHEDULED 가 아닌데 날짜가 남아 있으면 Apple 이 400 을 낸다 — 명시적으로 비운다.
+    if (releaseType === 'SCHEDULED')
+        attributes.earliestReleaseDate = earliestReleaseDate;
+    else if (earliestReleaseDate === undefined)
+        attributes.earliestReleaseDate = null;
+    await send('PATCH', `/appStoreVersions/${versionId}`, {
+        data: { type: 'appStoreVersions', id: versionId, attributes },
+    });
+    return getVersionSummary(versionId);
+}
+/**
+ * 단계적 출시(7일 램프) 제어.
+ *
+ * - enable   : 없으면 만들고(ACTIVE), PAUSED 면 재개한다
+ * - pause    : 일시중지 (되돌릴 수 있음)
+ * - resume   : 재개
+ * - complete : 남은 사용자에게 즉시 전체 공개 — 되돌릴 수 없다
+ * - disable  : 단계적 출시 자체를 제거. 출시 전이면 일반(전체) 출시로, 출시 후면 즉시 전체 공개가 된다
+ */
+export async function setPhasedRelease(args) {
+    const { versionId, action } = args;
+    const version = await getVersionSummary(versionId);
+    const current = await getPhasedRelease(versionId);
+    if (action === 'enable') {
+        if (!current) {
+            const created = await send('POST', '/appStoreVersionPhasedReleases', {
+                data: {
+                    type: 'appStoreVersionPhasedReleases',
+                    attributes: { phasedReleaseState: 'ACTIVE' },
+                    relationships: { appStoreVersion: { data: { type: 'appStoreVersions', id: versionId } } },
+                },
+            });
+            void created;
+        }
+        else if (current.state === 'PAUSED') {
+            await patchState(current.id, 'ACTIVE');
+        }
+        return { action, phased: await getPhasedRelease(versionId), version };
+    }
+    if (!current) {
+        throw new Error([
+            `❌ 이 버전에는 단계적 출시가 설정돼 있지 않다 (버전 상태: ${version.state ?? '알 수 없음'}).`,
+            '먼저 action="enable" 로 켜야 한다.',
+        ].join('\n'));
+    }
+    if (action === 'disable') {
+        await send('DELETE', `/appStoreVersionPhasedReleases/${current.id}`);
+        return { action, phased: null, version };
+    }
+    const next = action === 'pause' ? 'PAUSED' : action === 'resume' ? 'ACTIVE' : 'COMPLETE';
+    await patchState(current.id, next);
+    return { action, phased: await getPhasedRelease(versionId), version };
+}
+async function patchState(phasedReleaseId, state) {
+    await send('PATCH', `/appStoreVersionPhasedReleases/${phasedReleaseId}`, {
+        data: {
+            type: 'appStoreVersionPhasedReleases',
+            id: phasedReleaseId,
+            attributes: { phasedReleaseState: state },
+        },
+    });
+}

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;
+}>;