@yoonion/mimi-seed-mcp 0.3.26 → 0.3.28

package/dist/appstore/errors.js

@@ -0,0 +1,88 @@
+/**
+ * App Store Connect API 에러 친절화.
+ *
+ * Apple은 표준 JSON 에러 응답을 내려준다:
+ *   { "errors": [{ "code": "...", "title": "...", "detail": "...",
+ *                  "source": { "pointer": "/data/attributes/whatsNew" } }] }
+ *
+ * 실제 거부 사례에서 자주 만나는 코드별 hint 를 첨가해
+ * "App Store API 409: { errors: [...] }" 같은 raw dump 대신
+ * 무엇을 고쳐야 하는지 즉시 보이게 한다.
+ *
+ * 비표준 body (HTML, plain text, 빈 응답 등) 는 폴백으로 원본 보존.
+ */
+/** Apple 에러 코드 → 친절한 hint (실측 거부 사례 기반). */
+const CODE_HINTS = {
+    // What's New / localization 텍스트 검증 실패
+    INVALID_CHARACTERS: 'HTML 태그·금지 문자가 포함됐어요. 제출 전 lib/text-validators.ts 로 사전 검증 권장.',
+    // 버전 상태가 편집 불가 (READY_FOR_SALE / WAITING_FOR_REVIEW 등)
+    ENTITY_STATE_INVALID: '버전 상태가 편집 가능 단계가 아니에요 (이미 심사중/출시됨). 새 versionString 으로 appstore_create_version 필요할 수 있어요.',
+    // 필수 필드 누락
+    ENTITY_ERROR_ATTRIBUTE_REQUIRED: '필수 필드가 빠졌어요 — source.pointer 위치 확인.',
+    // 길이 / 형식 위반
+    ENTITY_ERROR_ATTRIBUTE_INVALID: '필드 값이 정책 위반(길이/형식). source.pointer 위치 확인.',
+    // 빌드 attach 시 빌드를 못 찾음
+    NOT_FOUND: '대상 리소스를 찾을 수 없어요 — id/versionId/buildId 가 유효한지, 동일 앱 소속인지 확인.',
+    // 권한 부족 (API Key role 문제)
+    FORBIDDEN_ERROR: 'API Key 권한 부족 — App Store Connect > Users and Access 에서 키 role 확인.',
+    // submit 직후 cancel 시도 (큐 진입 후)
+    STATE_ERROR: '현재 상태에서 허용되지 않는 작업. cancel_review 라면 큐 진입 후라서 불가 — 새 versionString 으로 우회.',
+};
+/** Apple 표준 에러 응답 파싱 시도. 실패하면 null 반환. */
+function parseAppleErrorBody(body) {
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        if (Array.isArray(parsed?.errors) && parsed.errors.length > 0) {
+            return parsed.errors;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 단일 Apple error → 한 줄 사람용 표기. */
+function formatAppleError(e) {
+    const code = e.code ?? 'UNKNOWN';
+    const detail = e.detail ?? e.title ?? '(no detail)';
+    const pointer = e.source?.pointer ?? e.source?.parameter;
+    const hint = e.code ? CODE_HINTS[e.code] : undefined;
+    const parts = [`[${code}] ${detail}`];
+    if (pointer)
+        parts.push(`@ ${pointer}`);
+    if (hint)
+        parts.push(`\n  💡 ${hint}`);
+    return parts.join(' ');
+}
+/**
+ * App Store API 응답 (status + raw body) 을 친절한 Error 로 변환.
+ *
+ * - 표준 Apple JSON: `App Store API {status}: [CODE] detail @ pointer 💡 hint` 형식.
+ *   여러 errors 가 있으면 줄바꿈으로 나열.
+ * - 비표준 body: 기존 형식(`App Store API {status}: {body}`) 그대로 보존.
+ *
+ * `Error.cause` 에 원본 `{ status, body, parsedErrors }` 첨부 — 호출자가 코드별 분기 필요 시 사용.
+ */
+export function friendlyAppStoreError(status, body) {
+    const errors = parseAppleErrorBody(body);
+    let message;
+    if (errors) {
+        const formatted = errors.map(formatAppleError).join('\n');
+        message = `App Store API ${status}:\n${formatted}`;
+    }
+    else {
+        message = `App Store API ${status}: ${body}`;
+    }
+    const err = new Error(message);
+    // 원본 보존 — 호출자 코드별 retry 분기용.
+    err.cause = { status, body, parsedErrors: errors ?? undefined };
+    return err;
+}
+// ── 테스트용 export ────────────────────────────────────────────
+export const __testing = {
+    CODE_HINTS,
+    parseAppleErrorBody,
+    formatAppleError,
+};

package/dist/appstore/setup-cli.js

@@ -42,7 +42,7 @@ async function main() {
     console.log('');
     console.log('  ✅ 연결 완료!');
     console.log('');
-    console.log('  이제 Claude Code에서:');
+    console.log('  이제 Claude Code 또는 Codex에서:');
     console.log('    "내 앱스토어 앱 목록 보여줘"');
     console.log('    "TestFlight 빌드 목록 보여줘"');
     console.log('');

package/dist/appstore/tools.d.ts

@@ -26,6 +26,29 @@ export declare function attachBuildToVersion(versionId: string, buildId: string)
     buildId: string;
     ok: boolean;
 }>;
+/**
+ * 가장 최신 VALID 빌드를 자동으로 찾아 versionId 에 attach.
+ *
+ * 흐름:
+ *   1. versionId → appId 역추적 (`getVersionAppAndPlatform`).
+ *   2. `listBuilds(appId)` 로 최근 10개 빌드 조회 (sort: uploadedDate desc).
+ *   3. `processingState === 'VALID'` 필터.
+ *   4. `minBuildNumber` 옵션 있으면 buildNumber 숫자 기준 필터.
+ *   5. buildNumber 숫자 최대값으로 정렬 → 1개 선택.
+ *   6. attach.
+ *
+ * 사용처: 1.4.x 같은 매 배포마다 `appstore_list_builds` → 수동 탐색 → `appstore_attach_build` 의
+ * 3-step 을 한 번에 줄임. 실수로 PROCESSING 중인 빌드를 attach 해서 심사 제출 시점에 깨지는
+ * 케이스도 차단.
+ */
+export declare function attachLatestValidBuild(versionId: string, opts?: {
+    minBuildNumber?: number;
+}): Promise<{
+    versionId: string;
+    attachedBuildId: string;
+    buildNumber: string;
+    uploadedDate?: string;
+}>;
 export declare function getVersionLocalizations(versionId: string): Promise<any>;
 export interface LocalizationUpdateFields {
     whatsNew?: string;
@@ -80,6 +103,31 @@ export interface ListCustomerReviewsOptions {
 }
 export declare function listCustomerReviews(appId: string, opts?: ListCustomerReviewsOptions): Promise<any>;
 export declare function createReviewResponse(reviewId: string, responseBody: string): Promise<any>;
+/**
+ * submit_for_review dry-run 프리뷰 — 비가역 제출 직전 사용자 확인용.
+ *
+ * 1.4.x 배포 사고 누적: submit 직후 cancel_review 가 큐 진입으로 막혀 새 versionString
+ * bump 으로 우회해야 하는 케이스가 반복됨 (reference_appstore_cancel_review_window).
+ * 호출자가 의도한 그 버전·빌드인지 미리 보여줘서 잘못된 versionId 제출 차단.
+ */
+export declare function buildSubmitForReviewPreview(versionId: string): Promise<{
+    versionId: string;
+    versionString?: string;
+    state?: string;
+    appId: string;
+    platform: string;
+    attachedBuild?: {
+        id: string;
+        buildNumber?: string;
+        uploadedDate?: string;
+        processingState?: string;
+    };
+    whatsNewByLocale: Array<{
+        locale: string;
+        excerpt: string;
+        length: number;
+    }>;
+}>;
 export declare function submitVersionForReview(versionId: string): Promise<{
     submissionId: string;
     appId: string;

package/dist/appstore/tools.js

@@ -1,4 +1,5 @@
 import { getAuthHeaders } from './auth.js';
+import { friendlyAppStoreError } from './errors.js';
 /**
  * App Store Connect API v1 래퍼
  * https://developer.apple.com/documentation/appstoreconnectapi
@@ -24,7 +25,7 @@ export async function apiGet(path, params) {
     const res = await fetch(url.toString(), { headers });
     if (!res.ok) {
         const body = await res.text();
-        throw new Error(`App Store API ${res.status}: ${body}`);
+        throw friendlyAppStoreError(res.status, body);
     }
     return res.json();
 }
@@ -44,7 +45,7 @@ async function apiPatch(path, body) {
     });
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`App Store API ${res.status}: ${text}`);
+        throw friendlyAppStoreError(res.status, text);
     }
     // 204 No Content 가능
     const text = await res.text();
@@ -66,7 +67,7 @@ async function apiPost(path, body) {
     });
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`App Store API ${res.status}: ${text}`);
+        throw friendlyAppStoreError(res.status, text);
     }
     // 201 Created — 본문에 created entity. 일부 엔드포인트는 204
     const text = await res.text();
@@ -147,6 +148,51 @@ export async function attachBuildToVersion(versionId, buildId) {
     });
     return { versionId, buildId, ok: true };
 }
+/**
+ * 가장 최신 VALID 빌드를 자동으로 찾아 versionId 에 attach.
+ *
+ * 흐름:
+ *   1. versionId → appId 역추적 (`getVersionAppAndPlatform`).
+ *   2. `listBuilds(appId)` 로 최근 10개 빌드 조회 (sort: uploadedDate desc).
+ *   3. `processingState === 'VALID'` 필터.
+ *   4. `minBuildNumber` 옵션 있으면 buildNumber 숫자 기준 필터.
+ *   5. buildNumber 숫자 최대값으로 정렬 → 1개 선택.
+ *   6. attach.
+ *
+ * 사용처: 1.4.x 같은 매 배포마다 `appstore_list_builds` → 수동 탐색 → `appstore_attach_build` 의
+ * 3-step 을 한 번에 줄임. 실수로 PROCESSING 중인 빌드를 attach 해서 심사 제출 시점에 깨지는
+ * 케이스도 차단.
+ */
+export async function attachLatestValidBuild(versionId, opts) {
+    const { appId } = await getVersionAppAndPlatform(versionId);
+    const builds = (await listBuilds(appId));
+    const valid = builds.filter((b) => b.processingState === 'VALID');
+    if (valid.length === 0) {
+        throw new Error(`appId=${appId} 에 VALID 빌드가 없어요 (최근 ${builds.length}개 확인). 빌드 PROCESSING 완료 대기 필요.`);
+    }
+    let candidates = valid;
+    if (opts?.minBuildNumber !== undefined) {
+        const min = opts.minBuildNumber;
+        candidates = valid.filter((b) => Number(b.version) >= min);
+        if (candidates.length === 0) {
+            throw new Error(`minBuildNumber=${min} 이상 VALID 빌드가 없어요. VALID 빌드: ${valid.map((b) => b.version).join(', ')}`);
+        }
+    }
+    // buildNumber 가 숫자 문자열이라는 가정 (TestFlight 표준). NaN 은 -Infinity 처리해 뒤로.
+    candidates.sort((a, b) => {
+        const an = Number(a.version);
+        const bn = Number(b.version);
+        return (isNaN(bn) ? -Infinity : bn) - (isNaN(an) ? -Infinity : an);
+    });
+    const target = candidates[0];
+    await attachBuildToVersion(versionId, target.id);
+    return {
+        versionId,
+        attachedBuildId: target.id,
+        buildNumber: target.version,
+        uploadedDate: target.uploadedDate,
+    };
+}
 // ─── 로컬라이제이션 (메타데이터) ───
 export async function getVersionLocalizations(versionId) {
     const data = await apiGet(`/appStoreVersions/${versionId}/appStoreVersionLocalizations`, {
@@ -426,6 +472,52 @@ async function isVersionAttached(submissionId, versionId) {
     const items = (data?.data ?? []);
     return items.some((it) => it?.relationships?.appStoreVersion?.data?.id === versionId);
 }
+/**
+ * submit_for_review dry-run 프리뷰 — 비가역 제출 직전 사용자 확인용.
+ *
+ * 1.4.x 배포 사고 누적: submit 직후 cancel_review 가 큐 진입으로 막혀 새 versionString
+ * bump 으로 우회해야 하는 케이스가 반복됨 (reference_appstore_cancel_review_window).
+ * 호출자가 의도한 그 버전·빌드인지 미리 보여줘서 잘못된 versionId 제출 차단.
+ */
+export async function buildSubmitForReviewPreview(versionId) {
+    const { appId, platform } = await getVersionAppAndPlatform(versionId);
+    // 버전 메타: versionString + state
+    const versionData = await apiGet(`/appStoreVersions/${versionId}`, {
+        'fields[appStoreVersions]': 'versionString,appStoreState',
+    }).catch(() => null);
+    const versionString = versionData?.data?.attributes?.versionString;
+    const state = versionData?.data?.attributes?.appStoreState;
+    // attached build
+    let attachedBuild;
+    const build = await apiGet(`/appStoreVersions/${versionId}/build`, {
+        'fields[builds]': 'version,uploadedDate,processingState',
+    }).catch(() => null);
+    if (build?.data?.id) {
+        attachedBuild = {
+            id: build.data.id,
+            buildNumber: build.data.attributes?.version,
+            uploadedDate: build.data.attributes?.uploadedDate,
+            processingState: build.data.attributes?.processingState,
+        };
+    }
+    const localizations = (await getVersionLocalizations(versionId).catch(() => []));
+    const whatsNewByLocale = localizations
+        .filter((l) => typeof l.whatsNew === 'string' && l.whatsNew.length > 0)
+        .map((l) => ({
+        locale: l.locale,
+        length: l.whatsNew.length,
+        excerpt: l.whatsNew.length > 200 ? `${l.whatsNew.slice(0, 200)}…` : l.whatsNew,
+    }));
+    return {
+        versionId,
+        versionString,
+        state,
+        appId,
+        platform,
+        attachedBuild,
+        whatsNewByLocale,
+    };
+}
 export async function submitVersionForReview(versionId) {
     const { appId, platform } = await getVersionAppAndPlatform(versionId);
     // 1. CREATED 상태의 reviewSubmission이 있으면 재사용, 없으면 새로 생성

package/dist/auth/bigquery-setup-cli.js

@@ -83,7 +83,7 @@ async function main() {
         }
     }
     console.log('');
-    console.log('  이제 Claude Code 에서:');
+    console.log('  이제 Claude Code 또는 Codex에서:');
     console.log('    "BigQuery 로 GA4 트래픽 분석해줘"');
     console.log('');
     rl.close();

package/dist/auth/cli.js

@@ -216,7 +216,7 @@ async function cmdLogin() {
     err('');
     err('  ✅ 연결 완료!');
     err('');
-    err('  이제 Claude Code에서 이렇게 쓸 수 있어:');
+    err('  이제 Claude Code 또는 Codex에서 이렇게 쓸 수 있어:');
     err('    "내 Firebase 프로젝트 보여줘"');
     err('    "새 Android 앱 등록해줘"');
     err('    "google-services.json 다운로드해줘"');

package/dist/auth/google-auth.d.ts

@@ -11,6 +11,13 @@ export declare function getStoredCredentials(): {
 } | null;
 export declare function saveCredentials(clientId: string, clientSecret: string): void;
 export declare function getStoredTokens(): StoredTokens | null;
+/**
+ * tokens.json mtime — 마지막 refresh 시각의 근사값.
+ * (saveTokens 가 매번 writeFileSync 으로 갱신하므로 mtime ≈ 마지막 갱신/저장.)
+ * Google refresh_token 은 7일(미인증 앱) ~ 6개월(인증 앱) 미사용 시 revoke 됨.
+ * auth_status 응답 enrichment 에 사용.
+ */
+export declare function getTokensLastRefreshMs(): number | null;
 export declare function createOAuth2Client(clientId: string, clientSecret: string): import("google-auth-library").OAuth2Client;
 /**
  * Get authenticated OAuth2 client.
@@ -59,4 +66,9 @@ export type RefreshStatus = {
  *
  * MCP 도구와 CLI 양쪽에서 공유.
  */
+/**
+ * 사전 갱신 마진. 기존 60_000(1분)에서 300_000(5분)으로 상향 — Google OAuth access_token 의
+ * 통상 lifetime 이 1h 이므로, 5분 마진으로 매 도구 호출 시 만료 임박 시 사전 갱신해
+ * "토큰 만료 → 도구 fail → 재호출" 의 단절 마찰 제거. 5분 마진은 평균 도구 작업 시간을 흡수.
+ */
 export declare function ensureFreshAccessToken(marginMs?: number): Promise<RefreshStatus>;

package/dist/auth/google-auth.js

@@ -60,6 +60,27 @@ export function getStoredTokens() {
         return null;
     }
 }
+/**
+ * tokens.json mtime — 마지막 refresh 시각의 근사값.
+ * (saveTokens 가 매번 writeFileSync 으로 갱신하므로 mtime ≈ 마지막 갱신/저장.)
+ * Google refresh_token 은 7일(미인증 앱) ~ 6개월(인증 앱) 미사용 시 revoke 됨.
+ * auth_status 응답 enrichment 에 사용.
+ */
+export function getTokensLastRefreshMs() {
+    const pathToRead = fs.existsSync(TOKEN_PATH)
+        ? TOKEN_PATH
+        : fs.existsSync(LEGACY_TOKEN_PATH)
+            ? LEGACY_TOKEN_PATH
+            : null;
+    if (!pathToRead)
+        return null;
+    try {
+        return fs.statSync(pathToRead).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
 function saveTokens(tokens) {
     ensureDir();
     fs.writeFileSync(TOKEN_PATH, JSON.stringify(tokens, null, 2), { mode: 0o600 });
@@ -189,13 +210,13 @@ export function startAuth(clientId, clientSecret, options = {}) {
                 };
                 saveTokens(stored);
                 res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                res.end(`
-          <html><body style="font-family:system-ui;display:flex;justify-content:center;align-items:center;height:100vh;margin:0">
-            <div style="text-align:center">
-              <h1>✅ Mimi Seed 인증 완료!</h1>
-              <p>이 창을 닫고 Claude Code로 돌아가세요.</p>
-            </div>
-          </body></html>
+                res.end(`
+          <html><body style="font-family:system-ui;display:flex;justify-content:center;align-items:center;height:100vh;margin:0">
+            <div style="text-align:center">
+              <h1>✅ Mimi Seed 인증 완료!</h1>
+              <p>이 창을 닫고 Claude Code 또는 Codex로 돌아가세요.</p>
+            </div>
+          </body></html>
         `);
                 server.close();
                 activeAuthServer = null;
@@ -253,7 +274,12 @@ export async function login(clientId, clientSecret) {
  *
  * MCP 도구와 CLI 양쪽에서 공유.
  */
-export async function ensureFreshAccessToken(marginMs = 60_000) {
+/**
+ * 사전 갱신 마진. 기존 60_000(1분)에서 300_000(5분)으로 상향 — Google OAuth access_token 의
+ * 통상 lifetime 이 1h 이므로, 5분 마진으로 매 도구 호출 시 만료 임박 시 사전 갱신해
+ * "토큰 만료 → 도구 fail → 재호출" 의 단절 마찰 제거. 5분 마진은 평균 도구 작업 시간을 흡수.
+ */
+export async function ensureFreshAccessToken(marginMs = 300_000) {
     const tokens = getStoredTokens();
     if (!tokens) {
         return {

package/dist/auth/playstore-setup-cli.js

@@ -55,7 +55,7 @@ async function main() {
     console.log('');
     console.log(`  ✅ 저장 완료! (${parsed.client_email})`);
     console.log('');
-    console.log('  이제 Claude Code에서:');
+    console.log('  이제 Claude Code 또는 Codex에서:');
     console.log('    "내 Play 스토어 앱 리스팅 보여줘"');
     console.log('    "Play 구독 상품 목록 보여줘"');
     console.log('');

package/dist/googleads/config.d.ts

@@ -0,0 +1,10 @@
+export interface GoogleAdsConfig {
+    developerToken: string;
+    customerId: string;
+    loginCustomerId?: string;
+}
+/** 하이픈 제거 (API는 숫자만 허용) */
+export declare function normalizeCustomerId(id: string): string;
+export declare function saveConfig(cfg: GoogleAdsConfig): void;
+export declare function loadConfig(): GoogleAdsConfig | null;
+export declare function requireConfig(): GoogleAdsConfig;

package/dist/googleads/config.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const CONFIG_DIR = path.join(os.homedir(), '.mimi-seed');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'google-ads.json');
+function ensureDir() {
+    if (!fs.existsSync(CONFIG_DIR))
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+}
+/** 하이픈 제거 (API는 숫자만 허용) */
+export function normalizeCustomerId(id) {
+    return id.replace(/-/g, '');
+}
+export function saveConfig(cfg) {
+    ensureDir();
+    const normalized = {
+        ...cfg,
+        customerId: normalizeCustomerId(cfg.customerId),
+        loginCustomerId: cfg.loginCustomerId ? normalizeCustomerId(cfg.loginCustomerId) : undefined,
+    };
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(normalized, null, 2), { mode: 0o600 });
+}
+export function loadConfig() {
+    if (!fs.existsSync(CONFIG_PATH))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function requireConfig() {
+    const cfg = loadConfig();
+    if (!cfg) {
+        throw new Error([
+            '❌ Google Ads 설정이 없어.',
+            '',
+            'googleads_save_config 도구로 먼저 설정해줘:',
+            '  - developerToken: Google Ads 콘솔 → 관리자 → API 센터에서 발급',
+            '  - customerId: Google Ads 계정 ID (예: 123-456-7890)',
+        ].join('\n'));
+    }
+    return cfg;
+}

package/dist/googleads/tools.d.ts

@@ -0,0 +1,48 @@
+import type { OAuth2Client } from 'google-auth-library';
+import type { GoogleAdsConfig } from './config.js';
+export interface DateRange {
+    startDate: string;
+    endDate: string;
+}
+export declare function listAccessibleCustomers(auth: OAuth2Client, cfg: GoogleAdsConfig): Promise<any>;
+export declare function listCampaigns(auth: OAuth2Client, cfg: GoogleAdsConfig): Promise<{
+    id: any;
+    name: any;
+    status: any;
+    channelType: any;
+    channelSubType: any;
+    startDate: any;
+    endDate: any;
+    dailyBudget: number;
+}[]>;
+export declare function getCampaignReport(auth: OAuth2Client, cfg: GoogleAdsConfig, range: DateRange): Promise<{
+    id: any;
+    name: any;
+    status: any;
+    channelType: any;
+    channelSubType: any;
+    clicks: number;
+    impressions: number;
+    cost: number;
+    conversions: number;
+    conversionsValue: number;
+    cpi: number;
+    ctr: number;
+    avgCpc: number;
+}[]>;
+export declare function getUacReport(auth: OAuth2Client, cfg: GoogleAdsConfig, range: DateRange): Promise<{
+    id: string;
+    name: string;
+    status: string;
+    subType: string;
+    clicks: number;
+    impressions: number;
+    cost: number;
+    installs: number;
+    installsValue: number;
+    cpi: number;
+    dateRange: {
+        from: string;
+        to: string;
+    };
+}[]>;