ios-app-review-plugin 1.0.0

package/src/asc/client.ts

@@ -0,0 +1,258 @@
+/**
+ * App Store Connect API Client
+ *
+ * Handles HTTP requests with rate limiting, retries, and pagination.
+ */
+
+import { getToken } from './auth.js';
+import {
+  ASCAPIError,
+  ASCAuthError,
+  ASCRateLimitError,
+} from './errors.js';
+import type {
+  ASCListResponse,
+  ASCErrorResponse,
+  ASCResource,
+} from './types.js';
+
+const BASE_URL = 'https://api.appstoreconnect.apple.com/v1';
+
+/**
+ * Rate limiter state
+ */
+interface RateLimiterState {
+  tokens: number;
+  lastRefill: number;
+  retryAfter?: number;
+}
+
+const RATE_LIMIT_TOKENS = 500; // 500 requests per hour
+const RATE_LIMIT_REFILL_INTERVAL = 60 * 60 * 1000; // 1 hour in ms
+
+let rateLimiter: RateLimiterState = {
+  tokens: RATE_LIMIT_TOKENS,
+  lastRefill: Date.now(),
+};
+
+/**
+ * Retry configuration
+ */
+const MAX_RETRIES = 3;
+const INITIAL_RETRY_DELAY = 1000; // 1 second
+
+/**
+ * Check and consume a rate limit token
+ */
+function consumeRateLimitToken(): boolean {
+  const now = Date.now();
+  const timeSinceRefill = now - rateLimiter.lastRefill;
+
+  // Refill tokens if an hour has passed
+  if (timeSinceRefill >= RATE_LIMIT_REFILL_INTERVAL) {
+    rateLimiter.tokens = RATE_LIMIT_TOKENS;
+    rateLimiter.lastRefill = now;
+  }
+
+  // Check if we need to wait for retry-after
+  if (rateLimiter.retryAfter && now < rateLimiter.retryAfter) {
+    return false;
+  }
+
+  if (rateLimiter.tokens > 0) {
+    rateLimiter.tokens--;
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Set retry-after from response header
+ */
+function setRetryAfter(seconds: number): void {
+  rateLimiter.retryAfter = Date.now() + seconds * 1000;
+}
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Parse error response
+ */
+async function parseErrorResponse(response: Response): Promise<ASCErrorResponse | null> {
+  try {
+    const text = await response.text();
+    if (text) {
+      return JSON.parse(text) as ASCErrorResponse;
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return null;
+}
+
+/**
+ * Make an authenticated request to the ASC API
+ */
+export async function request<T>(
+  path: string,
+  options: RequestInit = {}
+): Promise<T> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    // Check rate limit
+    if (!consumeRateLimitToken()) {
+      const waitTime = rateLimiter.retryAfter
+        ? rateLimiter.retryAfter - Date.now()
+        : RATE_LIMIT_REFILL_INTERVAL - (Date.now() - rateLimiter.lastRefill);
+
+      throw new ASCRateLimitError(Math.ceil(waitTime / 1000));
+    }
+
+    try {
+      const token = await getToken();
+
+      const url = path.startsWith('http') ? path : `${BASE_URL}${path}`;
+
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+          ...options.headers,
+        },
+      });
+
+      // Handle rate limiting
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        const seconds = retryAfter ? parseInt(retryAfter, 10) : 60;
+        setRetryAfter(seconds);
+
+        if (attempt < MAX_RETRIES) {
+          await sleep(seconds * 1000);
+          continue;
+        }
+
+        throw new ASCRateLimitError(seconds);
+      }
+
+      // Handle auth errors
+      if (response.status === 401 || response.status === 403) {
+        const errorResponse = await parseErrorResponse(response);
+        throw new ASCAuthError(
+          errorResponse?.errors?.[0]?.detail ?? 'Authentication failed'
+        );
+      }
+
+      // Handle server errors with retry
+      if (response.status >= 500 && attempt < MAX_RETRIES) {
+        lastError = new ASCAPIError(`Server error: ${response.status}`, response.status);
+        await sleep(INITIAL_RETRY_DELAY * Math.pow(2, attempt));
+        continue;
+      }
+
+      // Handle other errors
+      if (!response.ok) {
+        const errorResponse = await parseErrorResponse(response);
+        throw ASCAPIError.fromResponse(response.status, errorResponse?.errors);
+      }
+
+      // Parse successful response
+      const data = await response.json();
+      return data as T;
+    } catch (error) {
+      if (error instanceof ASCAPIError || error instanceof ASCAuthError || error instanceof ASCRateLimitError) {
+        throw error;
+      }
+
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Retry on network errors
+      if (attempt < MAX_RETRIES) {
+        await sleep(INITIAL_RETRY_DELAY * Math.pow(2, attempt));
+        continue;
+      }
+    }
+  }
+
+  throw lastError ?? new ASCAPIError('Request failed after retries', 0);
+}
+
+/**
+ * Make a GET request
+ */
+export async function get<T>(
+  path: string,
+  params?: Record<string, string | number | boolean | undefined>
+): Promise<T> {
+  let url = path;
+
+  if (params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined) {
+        searchParams.append(key, String(value));
+      }
+    }
+    const queryString = searchParams.toString();
+    if (queryString) {
+      url += (url.includes('?') ? '&' : '?') + queryString;
+    }
+  }
+
+  return request<T>(url, { method: 'GET' });
+}
+
+/**
+ * Fetch all pages of a paginated endpoint
+ */
+export async function getAllPages<T extends ASCResource>(
+  path: string,
+  params?: Record<string, string | number | boolean | undefined>,
+  maxPages = 10
+): Promise<T[]> {
+  const allData: T[] = [];
+  let nextUrl: string | undefined = path;
+  let pageCount = 0;
+
+  // Build initial URL with params
+  if (params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined) {
+        searchParams.append(key, String(value));
+      }
+    }
+    const queryString = searchParams.toString();
+    if (queryString) {
+      nextUrl += (nextUrl.includes('?') ? '&' : '?') + queryString;
+    }
+  }
+
+  while (nextUrl && pageCount < maxPages) {
+    const pageResponse: ASCListResponse<T> = await get<ASCListResponse<T>>(nextUrl);
+    allData.push(...pageResponse.data);
+
+    nextUrl = pageResponse.links?.next;
+    pageCount++;
+  }
+
+  return allData;
+}
+
+/**
+ * Reset rate limiter (useful for testing)
+ */
+export function resetRateLimiter(): void {
+  rateLimiter = {
+    tokens: RATE_LIMIT_TOKENS,
+    lastRefill: Date.now(),
+  };
+}

package/src/asc/endpoints/apps.ts

@@ -0,0 +1,115 @@
+/**
+ * App Store Connect App Endpoints
+ */
+
+import { get, getAllPages } from '../client.js';
+import { ASCAppNotFoundError } from '../errors.js';
+import type {
+  ASCResponse,
+  ASCListResponse,
+  App,
+  AppInfo,
+  AppInfoLocalization,
+} from '../types.js';
+
+/**
+ * Get an app by its bundle ID
+ */
+export async function getAppByBundleId(bundleId: string): Promise<App> {
+  const response = await get<ASCListResponse<App>>('/apps', {
+    'filter[bundleId]': bundleId,
+    'fields[apps]': 'name,bundleId,sku,primaryLocale,contentRightsDeclaration,isOrEverWasMadeForKids,availableInNewTerritories',
+    limit: 1,
+  });
+
+  const app = response.data[0];
+  if (!app) {
+    throw new ASCAppNotFoundError(bundleId);
+  }
+
+  return app;
+}
+
+/**
+ * Get an app by its ASC ID
+ */
+export async function getAppById(appId: string): Promise<App> {
+  const response = await get<ASCResponse<App>>(`/apps/${appId}`, {
+    'fields[apps]': 'name,bundleId,sku,primaryLocale,contentRightsDeclaration,isOrEverWasMadeForKids,availableInNewTerritories',
+  });
+
+  return response.data;
+}
+
+/**
+ * Get app info records for an app
+ */
+export async function getAppInfos(appId: string): Promise<AppInfo[]> {
+  return getAllPages<AppInfo>(`/apps/${appId}/appInfos`, {
+    'fields[appInfos]': 'appStoreState,appStoreAgeRating,brazilAgeRating,kidsAgeBand',
+  });
+}
+
+/**
+ * Get the current app info (non-released/editable version)
+ */
+export async function getCurrentAppInfo(appId: string): Promise<AppInfo | undefined> {
+  const appInfos = await getAppInfos(appId);
+
+  // Find the app info that is not yet released (editable)
+  // States that indicate editable: PREPARE_FOR_SUBMISSION, READY_FOR_REVIEW, WAITING_FOR_REVIEW, IN_REVIEW
+  const editableStates = [
+    'PREPARE_FOR_SUBMISSION',
+    'READY_FOR_REVIEW',
+    'WAITING_FOR_REVIEW',
+    'IN_REVIEW',
+    'PENDING_DEVELOPER_RELEASE',
+  ];
+
+  const currentInfo = appInfos.find((info) =>
+    editableStates.includes(info.attributes.appStoreState)
+  );
+
+  return currentInfo ?? appInfos[0];
+}
+
+/**
+ * Get app info localizations for an app info record
+ */
+export async function getAppInfoLocalizations(appInfoId: string): Promise<AppInfoLocalization[]> {
+  return getAllPages<AppInfoLocalization>(`/appInfos/${appInfoId}/appInfoLocalizations`, {
+    'fields[appInfoLocalizations]': 'locale,name,subtitle,privacyPolicyUrl,privacyChoicesUrl,privacyPolicyText',
+  });
+}
+
+/**
+ * Get a specific app info localization by locale
+ */
+export async function getAppInfoLocalization(
+  appInfoId: string,
+  locale: string
+): Promise<AppInfoLocalization | undefined> {
+  const localizations = await getAppInfoLocalizations(appInfoId);
+  return localizations.find((loc) => loc.attributes.locale === locale);
+}
+
+/**
+ * Get app with all related info in a single structure
+ */
+export interface AppWithInfo {
+  app: App;
+  appInfo: AppInfo | undefined;
+  localizations: AppInfoLocalization[];
+}
+
+export async function getAppWithInfo(bundleId: string): Promise<AppWithInfo> {
+  const app = await getAppByBundleId(bundleId);
+  const appInfo = await getCurrentAppInfo(app.id);
+
+  let localizations: AppInfoLocalization[] = [];
+  if (appInfo) {
+    localizations = await getAppInfoLocalizations(appInfo.id);
+  }
+
+  return { app, appInfo, localizations };
+}

package/src/asc/endpoints/iap.ts

@@ -0,0 +1,171 @@
+/**
+ * App Store Connect In-App Purchase Endpoints
+ */
+
+import { get, getAllPages } from '../client.js';
+import type {
+  ASCResponse,
+  InAppPurchase,
+  InAppPurchaseLocalization,
+  InAppPurchaseAppStoreReviewScreenshot,
+  IAPState,
+} from '../types.js';
+
+/**
+ * Get all in-app purchases for an app
+ */
+export async function getInAppPurchases(appId: string): Promise<InAppPurchase[]> {
+  return getAllPages<InAppPurchase>(`/apps/${appId}/inAppPurchasesV2`, {
+    'fields[inAppPurchases]': 'name,productId,inAppPurchaseType,state,reviewNote,familySharable,contentHosting',
+  });
+}
+
+/**
+ * Get a specific in-app purchase by ID
+ */
+export async function getInAppPurchaseById(iapId: string): Promise<InAppPurchase> {
+  const response = await get<ASCResponse<InAppPurchase>>(`/inAppPurchasesV2/${iapId}`, {
+    'fields[inAppPurchases]': 'name,productId,inAppPurchaseType,state,reviewNote,familySharable,contentHosting',
+  });
+
+  return response.data;
+}
+
+/**
+ * Get localizations for an in-app purchase
+ */
+export async function getIAPLocalizations(iapId: string): Promise<InAppPurchaseLocalization[]> {
+  return getAllPages<InAppPurchaseLocalization>(
+    `/inAppPurchasesV2/${iapId}/inAppPurchaseLocalizations`,
+    {
+      'fields[inAppPurchaseLocalizations]': 'locale,name,description',
+    }
+  );
+}
+
+/**
+ * Get review screenshot for an IAP
+ */
+export async function getIAPReviewScreenshot(
+  iapId: string
+): Promise<InAppPurchaseAppStoreReviewScreenshot | undefined> {
+  try {
+    const response = await get<ASCResponse<InAppPurchaseAppStoreReviewScreenshot>>(
+      `/inAppPurchasesV2/${iapId}/appStoreReviewScreenshot`,
+      {
+        'fields[inAppPurchaseAppStoreReviewScreenshots]': 'fileSize,fileName,assetDeliveryState,imageAsset',
+      }
+    );
+    return response.data;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * IAP validation result
+ */
+export interface IAPValidation {
+  iap: InAppPurchase;
+  localizations: InAppPurchaseLocalization[];
+  reviewScreenshot?: InAppPurchaseAppStoreReviewScreenshot | undefined;
+  issues: string[];
+  isReadyForSubmission: boolean;
+}
+
+/**
+ * States that indicate IAP is ready or nearly ready for submission
+ */
+const READY_STATES: IAPState[] = ['READY_TO_SUBMIT', 'WAITING_FOR_REVIEW', 'IN_REVIEW', 'APPROVED'];
+
+/**
+ * States that require action
+ */
+const ACTION_REQUIRED_STATES: IAPState[] = ['MISSING_METADATA', 'DEVELOPER_ACTION_NEEDED', 'REJECTED'];
+
+/**
+ * Validate an in-app purchase
+ */
+export async function validateIAP(iapId: string): Promise<IAPValidation> {
+  const [iap, localizations, reviewScreenshot] = await Promise.all([
+    getInAppPurchaseById(iapId),
+    getIAPLocalizations(iapId),
+    getIAPReviewScreenshot(iapId),
+  ]);
+
+  const issues: string[] = [];
+
+  // Check state
+  if (ACTION_REQUIRED_STATES.includes(iap.attributes.state)) {
+    issues.push(`IAP state requires action: ${iap.attributes.state}`);
+  }
+
+  // Check localizations
+  if (localizations.length === 0) {
+    issues.push('No localizations configured');
+  } else {
+    // Check for missing names/descriptions
+    for (const loc of localizations) {
+      if (!loc.attributes.name) {
+        issues.push(`Missing name for locale: ${loc.attributes.locale}`);
+      }
+      if (!loc.attributes.description) {
+        issues.push(`Missing description for locale: ${loc.attributes.locale}`);
+      }
+    }
+  }
+
+  // Check review screenshot (required for consumable/non-consumable)
+  const requiresScreenshot = ['CONSUMABLE', 'NON_CONSUMABLE'].includes(iap.attributes.inAppPurchaseType);
+  if (requiresScreenshot && !reviewScreenshot) {
+    issues.push('Review screenshot required but not uploaded');
+  }
+
+  // Check screenshot processing state
+  if (reviewScreenshot?.attributes.assetDeliveryState?.state === 'FAILED') {
+    issues.push('Review screenshot failed to process');
+  }
+
+  return {
+    iap,
+    localizations,
+    reviewScreenshot,
+    issues,
+    isReadyForSubmission: issues.length === 0 && READY_STATES.includes(iap.attributes.state),
+  };
+}
+
+/**
+ * Validate all IAPs for an app
+ */
+export async function validateAllIAPs(appId: string): Promise<IAPValidation[]> {
+  const iaps = await getInAppPurchases(appId);
+  const validations: IAPValidation[] = [];
+
+  for (const iap of iaps) {
+    const validation = await validateIAP(iap.id);
+    validations.push(validation);
+  }
+
+  return validations;
+}
+
+/**
+ * Get IAP state description
+ */
+export function getIAPStateDescription(state: IAPState): string {
+  const descriptions: Record<IAPState, string> = {
+    MISSING_METADATA: 'Missing required metadata',
+    READY_TO_SUBMIT: 'Ready to submit with next app version',
+    WAITING_FOR_REVIEW: 'Waiting for App Store review',
+    IN_REVIEW: 'Currently in review',
+    DEVELOPER_ACTION_NEEDED: 'Requires developer action',
+    PENDING_BINARY_APPROVAL: 'Pending binary approval',
+    APPROVED: 'Approved and active',
+    DEVELOPER_REMOVED_FROM_SALE: 'Removed from sale by developer',
+    REMOVED_FROM_SALE: 'Removed from sale',
+    REJECTED: 'Rejected by App Store review',
+  };
+
+  return descriptions[state] ?? state;
+}

package/src/asc/endpoints/screenshots.ts

@@ -0,0 +1,164 @@
+/**
+ * App Store Connect Screenshot Endpoints
+ */
+
+import { getAllPages } from '../client.js';
+import type {
+  AppScreenshotSet,
+  AppScreenshot,
+  ScreenshotDisplayType,
+} from '../types.js';
+
+/**
+ * Get all screenshot sets for a version localization
+ */
+export async function getScreenshotSets(
+  versionLocalizationId: string
+): Promise<AppScreenshotSet[]> {
+  return getAllPages<AppScreenshotSet>(
+    `/appStoreVersionLocalizations/${versionLocalizationId}/appScreenshotSets`,
+    {
+      'fields[appScreenshotSets]': 'screenshotDisplayType',
+    }
+  );
+}
+
+/**
+ * Get screenshots in a screenshot set
+ */
+export async function getScreenshots(screenshotSetId: string): Promise<AppScreenshot[]> {
+  return getAllPages<AppScreenshot>(
+    `/appScreenshotSets/${screenshotSetId}/appScreenshots`,
+    {
+      'fields[appScreenshots]': 'fileSize,fileName,sourceFileChecksum,imageAsset,assetToken,assetType,assetDeliveryState',
+    }
+  );
+}
+
+/**
+ * Get screenshot sets with their screenshots
+ */
+export interface ScreenshotSetWithScreenshots {
+  set: AppScreenshotSet;
+  screenshots: AppScreenshot[];
+}
+
+export async function getScreenshotSetsWithScreenshots(
+  versionLocalizationId: string
+): Promise<ScreenshotSetWithScreenshots[]> {
+  const sets = await getScreenshotSets(versionLocalizationId);
+
+  const results: ScreenshotSetWithScreenshots[] = [];
+
+  for (const set of sets) {
+    const screenshots = await getScreenshots(set.id);
+    results.push({ set, screenshots });
+  }
+
+  return results;
+}
+
+/**
+ * Required screenshot display types for iOS submission
+ */
+export const REQUIRED_IPHONE_DISPLAY_TYPES: ScreenshotDisplayType[] = [
+  'APP_IPHONE_67', // iPhone 14 Pro Max (6.7")
+  'APP_IPHONE_65', // iPhone 11 Pro Max (6.5")
+  'APP_IPHONE_55', // iPhone 8 Plus (5.5")
+];
+
+export const REQUIRED_IPAD_DISPLAY_TYPES: ScreenshotDisplayType[] = [
+  'APP_IPAD_PRO_3GEN_129', // iPad Pro 12.9" (3rd gen)
+  'APP_IPAD_PRO_129', // iPad Pro 12.9" (2nd gen)
+];
+
+/**
+ * All commonly required display types
+ */
+export const COMMONLY_REQUIRED_DISPLAY_TYPES: ScreenshotDisplayType[] = [
+  ...REQUIRED_IPHONE_DISPLAY_TYPES,
+  ...REQUIRED_IPAD_DISPLAY_TYPES,
+];
+
+/**
+ * Get display type description for human-readable output
+ */
+export function getDisplayTypeDescription(displayType: ScreenshotDisplayType): string {
+  const descriptions: Record<ScreenshotDisplayType, string> = {
+    APP_IPHONE_67: 'iPhone 6.7" (14 Pro Max, 15 Pro Max)',
+    APP_IPHONE_65: 'iPhone 6.5" (11 Pro Max, XS Max)',
+    APP_IPHONE_61: 'iPhone 6.1" (14/15, 14/15 Pro)',
+    APP_IPHONE_58: 'iPhone 5.8" (X, XS, 11 Pro)',
+    APP_IPHONE_55: 'iPhone 5.5" (6 Plus, 7 Plus, 8 Plus)',
+    APP_IPHONE_47: 'iPhone 4.7" (6, 7, 8, SE)',
+    APP_IPHONE_40: 'iPhone 4" (5, 5s, SE 1st gen)',
+    APP_IPHONE_35: 'iPhone 3.5" (4s and earlier)',
+    APP_IPAD_PRO_3GEN_129: 'iPad Pro 12.9" (3rd gen+)',
+    APP_IPAD_PRO_3GEN_11: 'iPad Pro 11"',
+    APP_IPAD_PRO_129: 'iPad Pro 12.9" (2nd gen)',
+    APP_IPAD_105: 'iPad 10.5"',
+    APP_IPAD_97: 'iPad 9.7"',
+    APP_WATCH_ULTRA: 'Apple Watch Ultra',
+    APP_WATCH_SERIES_7: 'Apple Watch Series 7+',
+    APP_WATCH_SERIES_4: 'Apple Watch Series 4-6',
+    APP_WATCH_SERIES_3: 'Apple Watch Series 3',
+    APP_DESKTOP: 'Mac Desktop',
+    APP_APPLE_TV: 'Apple TV',
+  };
+
+  return descriptions[displayType] ?? displayType;
+}
+
+/**
+ * Check screenshot validity
+ */
+export interface ScreenshotValidation {
+  displayType: ScreenshotDisplayType;
+  count: number;
+  isValid: boolean;
+  hasProcessingErrors: boolean;
+  processingState: string[];
+  issues: string[];
+}
+
+export function validateScreenshotSet(
+  set: AppScreenshotSet,
+  screenshots: AppScreenshot[]
+): ScreenshotValidation {
+  const issues: string[] = [];
+  const processingState: string[] = [];
+  let hasProcessingErrors = false;
+
+  // Check count (1-10 required)
+  if (screenshots.length === 0) {
+    issues.push('No screenshots uploaded');
+  } else if (screenshots.length > 10) {
+    issues.push(`Too many screenshots (${screenshots.length}/10 max)`);
+  }
+
+  // Check processing state
+  for (const screenshot of screenshots) {
+    const state = screenshot.attributes.assetDeliveryState?.state;
+    if (state) {
+      processingState.push(state);
+      if (state === 'FAILED') {
+        hasProcessingErrors = true;
+        const errors = screenshot.attributes.assetDeliveryState?.errors;
+        if (errors && errors.length > 0) {
+          issues.push(`Screenshot "${screenshot.attributes.fileName}" failed: ${errors[0]!.description}`);
+        } else {
+          issues.push(`Screenshot "${screenshot.attributes.fileName}" failed to process`);
+        }
+      }
+    }
+  }
+
+  return {
+    displayType: set.attributes.screenshotDisplayType,
+    count: screenshots.length,
+    isValid: issues.length === 0,
+    hasProcessingErrors,
+    processingState,
+    issues,
+  };
+}