pabal-store-api-mcp 1.1.0

package/README.md

@@ -0,0 +1,95 @@
+![Cover](public/cover.gif)
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=pabal-store-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBhYmFsLXN0b3JlLWFwaS1tY3AiXX0%3D)
+
+[![Pabal Web MCP (English)](https://img.shields.io/badge/Pabal%20Web%20MCP-English-blue)](https://pabal.quartz.best/docs/en-US/pabal-web-mcp/README) [![Pabal Web MCP (한국어)](https://img.shields.io/badge/Pabal%20Web%20MCP-한국어-green)](https://pabal.quartz.best/docs/ko-KR/pabal-web-mcp/README)
+
+# MCP server for App Store Connect & Play Console API
+
+Up-to-date ASO workflows exposed as MCP tools. Run it as a stdio MCP server (Claude Code, Cursor, MCP Inspector, etc.) to manage metadata, releases, and store syncs without leaving your AI client.
+
+> [!NOTE]
+> Runs 100% locally on your machine, so credentials and cached ASO data never leave your environment (store API calls are made directly from your device).
+
+<br>
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g pabal-store-api-mcp
+```
+
+### Configure
+
+1. Create config directory:
+
+```bash
+mkdir -p ~/.config/pabal-store-api-mcp
+chmod 700 ~/.config/pabal-store-api-mcp
+```
+
+2. Add your credentials to `~/.config/pabal-store-api-mcp/config.json`:
+   - **App Store Connect**: API key (`.p8` file) with `issuerId` and `keyId`
+   - **Google Play**: Service account JSON key
+
+3. Set up MCP client (Cursor, VS Code, Claude Code, etc.) to use `pabal-store-api-mcp`
+
+<br>
+
+## Features
+
+- ✅ **ASO Data Sync**: Pull/push metadata from App Store and Google Play
+- ✅ **Release Management**: Create versions and update release notes
+- ✅ **App Management**: Auto-register apps from store APIs
+- ✅ **100% Local**: All operations run on your machine
+
+<br>
+
+## MCP Tools
+
+- **Authentication**: `auth-check`
+- **App Management**: `apps-init`, `apps-add`, `apps-search`
+- **ASO Sync**: `aso-pull`, `aso-push`
+- **Release Management**: `release-check-versions`, `release-create`, `release-pull-notes`, `release-update-notes`
+
+<br>
+
+## Documentation
+
+📖 **[Pabal Web MCP Documentation (English)](https://pabal.quartz.best/docs/en-US/pabal-web-mcp/README)**
+📖 **[Pabal Web MCP 문서 (한국어)](https://pabal.quartz.best/docs/ko-KR/pabal-web-mcp/README)**
+
+<br>
+
+## Development
+
+```bash
+git clone https://github.com/quartz-labs-dev/pabal-store-api-mcp.git
+cd pabal-store-api-mcp
+yarn install
+yarn dev:mcp
+```
+
+<br>
+
+## License
+
+MIT
+
+<br>
+
+---
+
+<br>
+
+## 🌐 Pabal Web
+
+Want to manage ASO and SEO together? Check out **Pabal Web**.
+
+[![Pabal Web](public/pabal-web.png)](https://pabal.quartz.best/)
+
+**Pabal Web** is a Next.js-based web interface that provides a complete solution for unified management of ASO, SEO, Google Search Console indexing, and more.
+
+👉 [Visit Pabal Web](https://pabal.quartz.best/)

package/bin/pabal-mcp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// CLI entrypoint that starts the MCP server (npx entry)
+import { startServer } from "../dist/src/index.js";
+
+await startServer();

package/dist/src/core/clients/app-store-factory.d.ts

@@ -0,0 +1,29 @@
+import { AppStoreClient } from "../../packages/stores/app-store/client.js";
+import type { ClientFactoryResult } from "./types.js";
+/**
+ * Result type for App Store client creation
+ */
+export type AppStoreClientResult = ClientFactoryResult<AppStoreClient>;
+/**
+ * Configuration for App Store client creation
+ */
+export interface AppStoreClientConfig {
+    bundleId: string;
+}
+/**
+ * Create App Store client with fresh config loading and Result pattern
+ *
+ * Stateless factory - loads config on every call to ensure MCP works from any directory
+ *
+ * @param config - Bundle ID configuration
+ * @returns Result with client or error message
+ *
+ * @example
+ * const result = createAppStoreClient({ bundleId: "com.example.app" });
+ * if (result.success) {
+ *   const data = await result.client.getApp();
+ * } else {
+ *   console.error(result.error);
+ * }
+ */
+export declare function createAppStoreClient(config: AppStoreClientConfig): AppStoreClientResult;

package/dist/src/core/clients/app-store-factory.js

@@ -0,0 +1,72 @@
+import { AppError } from "../../packages/common/errors/app-error.js";
+import { ERROR_CODES } from "../../packages/common/errors/error-codes.js";
+import { HTTP_STATUS } from "../../packages/common/errors/status-codes.js";
+import { loadConfig } from "../../packages/configs/secrets-config/config.js";
+import { AppStoreClient } from "../../packages/stores/app-store/client.js";
+import { failure, isNonEmptyString, success } from "./client-factory-helpers.js";
+/**
+ * Create App Store client with fresh config loading and Result pattern
+ *
+ * Stateless factory - loads config on every call to ensure MCP works from any directory
+ *
+ * @param config - Bundle ID configuration
+ * @returns Result with client or error message
+ *
+ * @example
+ * const result = createAppStoreClient({ bundleId: "com.example.app" });
+ * if (result.success) {
+ *   const data = await result.client.getApp();
+ * } else {
+ *   console.error(result.error);
+ * }
+ */
+export function createAppStoreClient(config) {
+    // Validate input
+    if (!config) {
+        return failure(AppError.badRequest(ERROR_CODES.APP_STORE_CLIENT_CONFIG_MISSING, "App Store client configuration is missing"));
+    }
+    const { bundleId } = config;
+    if (!isNonEmptyString(bundleId)) {
+        return failure(AppError.validation(ERROR_CODES.APP_STORE_BUNDLE_ID_INVALID, "Bundle ID is required and must be a non-empty string"));
+    }
+    // Load fresh config (stateless - works from any directory)
+    let appStoreConfig;
+    try {
+        const fullConfig = loadConfig();
+        appStoreConfig = fullConfig.appStore;
+    }
+    catch (error) {
+        return failure(AppError.wrap(error, HTTP_STATUS.INTERNAL_SERVER_ERROR, ERROR_CODES.APP_STORE_CONFIG_LOAD_FAILED, "Failed to load App Store configuration"));
+    }
+    // Validate required credentials
+    if (!appStoreConfig) {
+        return failure(AppError.configMissing(ERROR_CODES.APP_STORE_CONFIG_MISSING, "App Store configuration is missing in config file"));
+    }
+    const { issuerId, keyId, privateKey } = appStoreConfig;
+    if (!isNonEmptyString(issuerId)) {
+        return failure(AppError.validation(ERROR_CODES.APP_STORE_ISSUER_ID_INVALID, "App Store Issuer ID is required in configuration"));
+    }
+    if (!isNonEmptyString(keyId)) {
+        return failure(AppError.validation(ERROR_CODES.APP_STORE_KEY_ID_INVALID, "App Store Key ID is required in configuration"));
+    }
+    if (!isNonEmptyString(privateKey)) {
+        return failure(AppError.validation(ERROR_CODES.APP_STORE_PRIVATE_KEY_INVALID, "App Store Private Key is required in configuration"));
+    }
+    // Validate private key format
+    if (!privateKey.includes("BEGIN PRIVATE KEY")) {
+        return failure(AppError.validation(ERROR_CODES.APP_STORE_PRIVATE_KEY_FORMAT_INVALID, "Invalid Private Key format. PEM format private key is required (must contain 'BEGIN PRIVATE KEY')"));
+    }
+    // Create client
+    try {
+        const client = new AppStoreClient({
+            bundleId,
+            issuerId,
+            keyId,
+            privateKey,
+        });
+        return success(client);
+    }
+    catch (error) {
+        return failure(AppError.wrap(error, HTTP_STATUS.INTERNAL_SERVER_ERROR, ERROR_CODES.APP_STORE_CLIENT_CREATE_FAILED, "Failed to create App Store client"));
+    }
+}

package/dist/src/core/clients/client-factory-helpers.d.ts

@@ -0,0 +1,7 @@
+import { AppError } from "../../packages/common/errors/app-error.js";
+import type { ClientFactoryResult } from "./types.js";
+export type { ClientFactoryResult } from "./types.js";
+export declare const success: <TClient>(client: TClient) => ClientFactoryResult<TClient>;
+export declare const failure: <TClient>(error: AppError) => ClientFactoryResult<TClient>;
+export declare const toErrorMessage: (error: unknown) => string;
+export declare const isNonEmptyString: (value: unknown) => value is string;

package/dist/src/core/clients/client-factory-helpers.js

@@ -0,0 +1,10 @@
+export const success = (client) => ({
+    success: true,
+    client,
+});
+export const failure = (error) => ({
+    success: false,
+    error,
+});
+export const toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+export const isNonEmptyString = (value) => typeof value === "string" && Boolean(value.trim());

package/dist/src/core/clients/google-play-factory.d.ts

@@ -0,0 +1,29 @@
+import { GooglePlayClient } from "../../packages/stores/play-store/client.js";
+import type { ClientFactoryResult } from "./types.js";
+/**
+ * Result type for Google Play client creation
+ */
+export type GooglePlayClientResult = ClientFactoryResult<GooglePlayClient>;
+/**
+ * Configuration for Google Play client creation
+ */
+export interface GooglePlayClientConfig {
+    packageName: string;
+}
+/**
+ * Create Google Play client with fresh config loading and Result pattern
+ *
+ * Stateless factory - loads config on every call to ensure MCP works from any directory
+ *
+ * @param config - Package name configuration
+ * @returns Result with client or error message
+ *
+ * @example
+ * const result = createGooglePlayClient({ packageName: "com.example.app" });
+ * if (result.success) {
+ *   const data = await result.client.getApp();
+ * } else {
+ *   console.error(result.error);
+ * }
+ */
+export declare function createGooglePlayClient(config: GooglePlayClientConfig): GooglePlayClientResult;

package/dist/src/core/clients/google-play-factory.js

@@ -0,0 +1,72 @@
+import { AppError } from "../../packages/common/errors/app-error.js";
+import { ERROR_CODES } from "../../packages/common/errors/error-codes.js";
+import { HTTP_STATUS } from "../../packages/common/errors/status-codes.js";
+import { loadConfig } from "../../packages/configs/secrets-config/config.js";
+import { GooglePlayClient } from "../../packages/stores/play-store/client.js";
+import { failure, isNonEmptyString, success } from "./client-factory-helpers.js";
+/**
+ * Create Google Play client with fresh config loading and Result pattern
+ *
+ * Stateless factory - loads config on every call to ensure MCP works from any directory
+ *
+ * @param config - Package name configuration
+ * @returns Result with client or error message
+ *
+ * @example
+ * const result = createGooglePlayClient({ packageName: "com.example.app" });
+ * if (result.success) {
+ *   const data = await result.client.getApp();
+ * } else {
+ *   console.error(result.error);
+ * }
+ */
+export function createGooglePlayClient(config) {
+    // Validate input
+    if (!config) {
+        return failure(AppError.badRequest(ERROR_CODES.GOOGLE_PLAY_CLIENT_CONFIG_MISSING, "Google Play client configuration is missing"));
+    }
+    const { packageName } = config;
+    if (!isNonEmptyString(packageName)) {
+        return failure(AppError.validation(ERROR_CODES.GOOGLE_PLAY_PACKAGE_NAME_INVALID, "Package name is required and must be a non-empty string"));
+    }
+    // Load fresh config (stateless - works from any directory)
+    let playStoreConfig;
+    try {
+        const fullConfig = loadConfig();
+        playStoreConfig = fullConfig.playStore;
+    }
+    catch (error) {
+        return failure(AppError.wrap(error, HTTP_STATUS.INTERNAL_SERVER_ERROR, ERROR_CODES.GOOGLE_PLAY_CONFIG_LOAD_FAILED, "Failed to load Google Play configuration"));
+    }
+    // Validate required credentials
+    if (!playStoreConfig) {
+        return failure(AppError.configMissing(ERROR_CODES.GOOGLE_PLAY_CONFIG_MISSING, "Google Play configuration is missing in config file"));
+    }
+    const { serviceAccountJson } = playStoreConfig;
+    if (!isNonEmptyString(serviceAccountJson)) {
+        return failure(AppError.validation(ERROR_CODES.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_INVALID, "Google Play service account JSON is required in configuration"));
+    }
+    // Parse and validate service account JSON
+    let serviceAccountKey;
+    try {
+        const parsed = JSON.parse(serviceAccountJson);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return failure(AppError.validation(ERROR_CODES.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_FORMAT_INVALID, "Service account JSON must be a valid JSON object"));
+        }
+        serviceAccountKey = parsed;
+    }
+    catch (error) {
+        return failure(AppError.wrap(error, HTTP_STATUS.UNPROCESSABLE_ENTITY, ERROR_CODES.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_PARSE_FAILED, "Invalid Google Play service account JSON"));
+    }
+    // Create client
+    try {
+        const client = new GooglePlayClient({
+            packageName,
+            serviceAccountKey,
+        });
+        return success(client);
+    }
+    catch (error) {
+        return failure(AppError.wrap(error, HTTP_STATUS.INTERNAL_SERVER_ERROR, ERROR_CODES.GOOGLE_PLAY_CLIENT_CREATE_FAILED, "Failed to create Google Play client"));
+    }
+}

package/dist/src/core/clients/types.d.ts

@@ -0,0 +1,8 @@
+import type { AppError } from "../../packages/common/errors/app-error.js";
+export type ClientFactoryResult<TClient> = {
+    success: true;
+    client: TClient;
+} | {
+    success: false;
+    error: AppError;
+};

package/dist/src/core/clients/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/helpers/formatters.d.ts

@@ -0,0 +1,3 @@
+import type { PushAsoResult, UpdatedReleaseNotesResult } from "../../core/services/types.js";
+export declare function formatPushResult(storeLabel: "App Store" | "Google Play", result: PushAsoResult): string;
+export declare const formatReleaseNotesUpdate: (storeLabel: "App Store" | "Google Play", result: UpdatedReleaseNotesResult) => string[];

package/dist/src/core/helpers/formatters.js

@@ -0,0 +1,38 @@
+const fieldDisplayNames = {
+    name: "Name",
+    subtitle: "Subtitle",
+};
+function formatFailedFields(failedFields) {
+    return failedFields
+        .map((f) => {
+        const fieldNames = f.fields.map((field) => fieldDisplayNames[field] || field);
+        return `   • ${f.locale}: ${fieldNames.join(", ")}`;
+    })
+        .join("\n");
+}
+export function formatPushResult(storeLabel, result) {
+    if (!result.success) {
+        if (result.needsNewVersion && result.versionInfo) {
+            const { versionString, versionId } = result.versionInfo;
+            return `✅ New version ${versionString} created (Version ID: ${versionId})`;
+        }
+        return `❌ ${storeLabel} push failed: ${result.error.message}`;
+    }
+    if (result.failedFields && result.failedFields.length > 0) {
+        return `⚠️  ${storeLabel} data pushed with partial failures (${result.localesPushed.length} locales)\n${formatFailedFields(result.failedFields)}`;
+    }
+    return `✅ ${storeLabel} data pushed (${result.localesPushed.length} locales)`;
+}
+export const formatReleaseNotesUpdate = (storeLabel, result) => {
+    const lines = [];
+    lines.push(`**${storeLabel}**`);
+    if (result.updated.length > 0) {
+        lines.push(`  ✅ Updated: ${result.updated.join(", ")}`);
+    }
+    if (result.failed.length > 0) {
+        for (const fail of result.failed) {
+            lines.push(`  ❌ ${fail.locale}: ${fail.error}`);
+        }
+    }
+    return lines;
+};

package/dist/src/core/helpers/registration.d.ts

@@ -0,0 +1,21 @@
+import type { RegisteredAppStoreInfo, RegisteredGooglePlayInfo } from "../../packages/configs/secrets-config/registered-apps.js";
+type AppStoreAppInfo = {
+    found: boolean;
+    appId?: string;
+    name?: string;
+    supportedLocales?: string[];
+};
+type GooglePlayAppInfo = {
+    found: boolean;
+    name?: string;
+    supportedLocales?: string[];
+};
+export declare function toRegisteredAppStoreInfo({ bundleId, appInfo, }: {
+    bundleId: string;
+    appInfo: AppStoreAppInfo;
+}): RegisteredAppStoreInfo | undefined;
+export declare function toRegisteredGooglePlayInfo({ packageName, appInfo, }: {
+    packageName: string;
+    appInfo: GooglePlayAppInfo;
+}): RegisteredGooglePlayInfo | undefined;
+export {};

package/dist/src/core/helpers/registration.js

@@ -0,0 +1,21 @@
+export function toRegisteredAppStoreInfo({ bundleId, appInfo, }) {
+    if (!appInfo.found) {
+        return undefined;
+    }
+    return {
+        bundleId,
+        appId: appInfo.appId,
+        name: appInfo.name,
+        supportedLocales: appInfo.supportedLocales,
+    };
+}
+export function toRegisteredGooglePlayInfo({ packageName, appInfo, }) {
+    if (!appInfo.found) {
+        return undefined;
+    }
+    return {
+        packageName,
+        name: appInfo.name,
+        supportedLocales: appInfo.supportedLocales,
+    };
+}

package/dist/src/core/helpers/translate-release-notes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Release notes translation utilities.
+ * Prepares translation requests per store and gathers supported locales from registered apps.
+ */
+import type { RegisteredApp } from "../../packages/configs/secrets-config/registered-apps.js";
+import type { StoreType } from "../../packages/configs/aso-config/types.js";
+export interface TranslationRequest {
+    sourceText: string;
+    sourceLocale: string;
+    targetLocales: string[];
+    store: StoreType;
+}
+/**
+ * Collect supported locales from registered app info
+ */
+export declare function collectSupportedLocales({ app, store, }: {
+    app: RegisteredApp;
+    store: StoreType;
+}): {
+    appStore: string[];
+    googlePlay: string[];
+};
+/**
+ * Create translation requests per store
+ */
+export declare function createTranslationRequests({ store, targetLocales, sourceLocale, sourceText, }: {
+    store: StoreType;
+    targetLocales: {
+        appStore: string[];
+        googlePlay: string[];
+    };
+    sourceLocale: string;
+    sourceText: string;
+}): TranslationRequest[];
+/**
+ * Separate translations by store
+ */
+export declare function separateTranslationsByStore({ store, translations, app, sourceLocale, }: {
+    store: StoreType;
+    translations: Record<string, string>;
+    app: RegisteredApp;
+    sourceLocale: string;
+}): {
+    appStore: Record<string, string>;
+    googlePlay: Record<string, string>;
+};

package/dist/src/core/helpers/translate-release-notes.js

@@ -0,0 +1,87 @@
+/**
+ * Release notes translation utilities.
+ * Prepares translation requests per store and gathers supported locales from registered apps.
+ */
+/**
+ * Collect supported locales from registered app info
+ */
+export function collectSupportedLocales({ app, store, }) {
+    const appStoreLocales = [];
+    const googlePlayLocales = [];
+    if ((store === "both" || store === "appStore") &&
+        app.appStore?.supportedLocales) {
+        appStoreLocales.push(...app.appStore.supportedLocales);
+    }
+    if ((store === "both" || store === "googlePlay") &&
+        app.googlePlay?.supportedLocales) {
+        googlePlayLocales.push(...app.googlePlay.supportedLocales);
+    }
+    return {
+        appStore: appStoreLocales,
+        googlePlay: googlePlayLocales,
+    };
+}
+/**
+ * Create translation requests per store
+ */
+export function createTranslationRequests({ store, targetLocales, sourceLocale, sourceText, }) {
+    const requests = [];
+    if (store === "both" || store === "appStore") {
+        if (targetLocales.appStore.length > 0) {
+            requests.push({
+                store: "appStore",
+                sourceText,
+                sourceLocale,
+                targetLocales: targetLocales.appStore,
+            });
+        }
+    }
+    if (store === "both" || store === "googlePlay") {
+        if (targetLocales.googlePlay.length > 0) {
+            requests.push({
+                store: "googlePlay",
+                sourceText,
+                sourceLocale,
+                targetLocales: targetLocales.googlePlay,
+            });
+        }
+    }
+    return requests;
+}
+/**
+ * Separate translations by store
+ */
+export function separateTranslationsByStore({ store, translations, app, sourceLocale, }) {
+    const appStoreTranslations = {};
+    const googlePlayTranslations = {};
+    const appStoreLocales = app.appStore?.supportedLocales;
+    const googlePlayLocales = app.googlePlay?.supportedLocales;
+    for (const [locale, text] of Object.entries(translations)) {
+        if (store === "both" || store === "appStore") {
+            if (!appStoreLocales || appStoreLocales.includes(locale)) {
+                appStoreTranslations[locale] = text;
+            }
+        }
+        if (store === "both" || store === "googlePlay") {
+            if (!googlePlayLocales || googlePlayLocales.includes(locale)) {
+                googlePlayTranslations[locale] = text;
+            }
+        }
+    }
+    // Always include sourceLocale if provided and missing
+    if (store === "both" || store === "appStore") {
+        if (translations[sourceLocale] && !(sourceLocale in appStoreTranslations)) {
+            appStoreTranslations[sourceLocale] = translations[sourceLocale];
+        }
+    }
+    if (store === "both" || store === "googlePlay") {
+        if (translations[sourceLocale] &&
+            !(sourceLocale in googlePlayTranslations)) {
+            googlePlayTranslations[sourceLocale] = translations[sourceLocale];
+        }
+    }
+    return {
+        appStore: appStoreTranslations,
+        googlePlay: googlePlayTranslations,
+    };
+}

package/dist/src/core/services/app-resolution-service.d.ts

@@ -0,0 +1,14 @@
+import { type ResolvedAppContext, type ServiceResult } from "./types.js";
+interface ResolveAppOptions {
+    slug?: string;
+    bundleId?: string;
+    packageName?: string;
+}
+/**
+ * Resolve registered app and store identifiers from user input.
+ * Separates "which store data is available" from tool-level orchestration.
+ */
+export declare class AppResolutionService {
+    resolve(options: ResolveAppOptions): ServiceResult<ResolvedAppContext>;
+}
+export {};

package/dist/src/core/services/app-resolution-service.js

@@ -0,0 +1,35 @@
+import { AppError } from "../../packages/common/errors/app-error.js";
+import { ERROR_CODES } from "../../packages/common/errors/error-codes.js";
+import { findApp } from "../../packages/configs/secrets-config/registered-apps.js";
+import { HTTP_STATUS } from "../../packages/common/errors/status-codes.js";
+import { serviceFailure, serviceSuccess } from "./service-helpers.js";
+/**
+ * Resolve registered app and store identifiers from user input.
+ * Separates "which store data is available" from tool-level orchestration.
+ */
+export class AppResolutionService {
+    resolve(options) {
+        const { slug, bundleId, packageName } = options;
+        const identifier = slug || bundleId || packageName;
+        if (!identifier) {
+            return serviceFailure(AppError.validation(ERROR_CODES.APP_IDENTIFIER_MISSING, "❌ App not found. Please provide app (slug), packageName, or bundleId."));
+        }
+        try {
+            const app = findApp(identifier);
+            if (!app) {
+                return serviceFailure(AppError.notFound(ERROR_CODES.APP_NOT_FOUND, `❌ App registered with "${identifier}" not found. Check registered apps using apps-search.`));
+            }
+            return serviceSuccess({
+                app,
+                slug: app.slug,
+                bundleId: bundleId ?? app.appStore?.bundleId,
+                packageName: packageName ?? app.googlePlay?.packageName,
+                hasAppStore: Boolean(app.appStore),
+                hasGooglePlay: Boolean(app.googlePlay),
+            });
+        }
+        catch (error) {
+            return serviceFailure(AppError.wrap(error, HTTP_STATUS.INTERNAL_SERVER_ERROR, ERROR_CODES.APP_RESOLUTION_FAILED, "Failed to resolve app"));
+        }
+    }
+}

package/dist/src/core/services/app-store-service.d.ts

@@ -0,0 +1,41 @@
+import type { AppStoreReleaseNote } from "../../packages/configs/aso-config/types.js";
+import type { PreparedAsoData } from "../../packages/configs/aso-config/utils.js";
+import type { EnvConfig } from "../../packages/configs/secrets-config/types.js";
+import type { AppStoreClient } from "../../packages/stores/app-store/client.js";
+import { type MaybeResult, type ServiceResult, type StoreAppSummary, type AppStoreVersionInfo, type UpdatedReleaseNotesResult, type PushAsoResult, type CreatedAppStoreVersion, type VerifyAuthResult } from "./types.js";
+interface AppStoreAppInfo {
+    appId?: string;
+    name?: string;
+    supportedLocales?: string[];
+}
+/**
+ * App Store-facing service layer that wraps client creation and common operations.
+ * Keeps MCP tools independent from client factories and SDK details.
+ */
+export declare class AppStoreService {
+    private getClientOrThrow;
+    createClient(bundleId: string): ServiceResult<AppStoreClient>;
+    /**
+     * List released apps. Uses a fresh client to ensure working directory independence.
+     */
+    listReleasedApps(): Promise<ServiceResult<StoreAppSummary[]>>;
+    /**
+     * Fetch a single app info (with locales) by bundleId.
+     */
+    fetchAppInfo(bundleId: string, existingClient?: AppStoreClient): Promise<MaybeResult<AppStoreAppInfo>>;
+    getLatestVersion(bundleId: string, existingClient?: AppStoreClient): Promise<MaybeResult<AppStoreVersionInfo>>;
+    updateReleaseNotes(bundleId: string, releaseNotes: Record<string, string>, versionId?: string, supportedLocales?: string[]): Promise<ServiceResult<UpdatedReleaseNotesResult>>;
+    pullReleaseNotes(bundleId: string): Promise<ServiceResult<AppStoreReleaseNote[]>>;
+    createVersion(bundleId: string, versionString: string, autoIncrement?: boolean): Promise<ServiceResult<CreatedAppStoreVersion>>;
+    pushAsoData({ config, bundleId, localAsoData, appStoreDataPath, }: {
+        config: EnvConfig;
+        bundleId?: string;
+        localAsoData: PreparedAsoData;
+        appStoreDataPath: string;
+    }): Promise<PushAsoResult>;
+    verifyAuth(expirationSeconds?: number): Promise<VerifyAuthResult<{
+        header: Record<string, unknown>;
+        payload: Record<string, unknown>;
+    }>>;
+}
+export {};