Antigravity × App Store Connect API: Complete Automation Guide for Revenue, ASO & Reviews

import axios from 'axios';
import * as zlib from 'zlib';
import { promisify } from 'util';
 
const gunzip = promisify(zlib.gunzip);
const BASE_URL = 'https://api.appstoreconnect.apple.com/v1';
 
interface SalesRecord {
  appId: string;
  title: string;
  units: number;
  developerProceeds: number;
  currency: string;
  storefront: string;      // Country code: JP, US, GB, etc.
  productType: string;     // '1' = paid download, '7' = free, 'F1' = subscription
}
 
async function fetchDailySalesReport(
  auth: AppStoreConnectAuth,
  vendorNumber: string,
  date: string   // 'YYYY-MM-DD' — use yesterday's date
): Promise<SalesRecord[]> {
  const params = new URLSearchParams({
    'filter[frequency]': 'DAILY',
    'filter[reportDate]': date,
    'filter[reportType]': 'SALES',
    'filter[vendorNumber]': vendorNumber,
    'filter[version]': '1_0',
  });
 
  try {
    const response = await axios.get(
      `${BASE_URL}/salesReports?${params.toString()}`,
      {
        headers: {
          ...auth.getAuthHeader(),
          'Accept': 'application/a-gzip',
        },
        responseType: 'arraybuffer',
      }
    );
 
    const decompressed = await gunzip(Buffer.from(response.data));
    return parseSalesTsv(decompressed.toString('utf8'));
  } catch (error) {
    if (axios.isAxiosError(error) && error.response?.status === 404) {
      // Report not yet generated — Apple typically creates them between 2–5 AM JST
      return [];
    }
    throw error;
  }
}
 
function parseSalesTsv(tsv: string): SalesRecord[] {
  const lines = tsv.split('\n').filter(line => line.trim());
  if (lines.length < 2) return [];
 
  const headers = lines[0].split('\t');
  return lines.slice(1).map(line => {
    const values = line.split('\t');
    const row: Record<string, string> = {};
    headers.forEach((h, i) => { row[h] = values[i] || ''; });
 
    return {
      appId: row['Apple Identifier'],
      title: row['Title'],
      units: parseInt(row['Units'] || '0', 10),
      developerProceeds: parseFloat(row['Developer Proceeds'] || '0'),
      currency: row['Currency of Proceeds'],
      storefront: row['Storefront'],
      productType: row['Product Type Identifier'],
    };
  });
}
 
// Expected output:
// [
//   { appId: '123456789', title: 'MyApp', units: 12, developerProceeds: 8.40, currency: 'JPY', storefront: 'JP', productType: '7' },
//   { appId: '123456789', title: 'MyApp', units: 3, developerProceeds: 2.25, currency: 'USD', storefront: 'US', productType: '1' },
// ]

async function fetchWithRetry(
  fetchFn: () => Promise<SalesRecord[]>,
  maxRetries = 3,
  delayMs = 30_000
): Promise<SalesRecord[]> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const result = await fetchFn();
    if (result.length > 0) return result;
    if (attempt < maxRetries - 1) {
      console.log(`Report not ready, retrying in ${delayMs / 1000}s (${attempt + 1}/${maxRetries})`);
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }
  return [];
}

interface Review {
  id: string;
  authorName: string;
  rating: number;
  title: string;
  body: string;
  createdDate: string;
  territory: string;
  responded: boolean;
}
 
async function fetchRecentReviews(
  auth: AppStoreConnectAuth,
  appId: string,
  afterDate: Date
): Promise<Review[]> {
  const allReviews: Review[] = [];
  let nextUrl: string | null =
    `${BASE_URL}/apps/${appId}/customerReviews?limit=200&sort=-createdDate`;
 
  while (nextUrl) {
    const response = await axios.get(nextUrl, { headers: auth.getAuthHeader() });
    const { data, links } = response.data;
 
    for (const item of data) {
      const review: Review = {
        id: item.id,
        ...item.attributes,
        responded: !!item.relationships?.response?.data,
      };
 
      // Stop paginating once we've gone past the target date
      if (new Date(review.createdDate) < afterDate) return allReviews;
      allReviews.push(review);
    }
 
    nextUrl = links?.next ?? null;
  }
 
  return allReviews;
}

import { WebClient } from '@slack/web-api';
 
const slack = new WebClient(process.env.SLACK_BOT_TOKEN);
 
async function alertNegativeReviews(
  auth: AppStoreConnectAuth,
  appId: string,
  appName: string
): Promise<void> {
  const since = new Date(Date.now() - 24 * 60 * 60 * 1000);
  const reviews = await fetchRecentReviews(auth, appId, since);
  const negative = reviews.filter(r => r.rating <= 2);
 
  for (const review of negative) {
    const stars = '★'.repeat(review.rating) + '☆'.repeat(5 - review.rating);
    await slack.chat.postMessage({
      channel: process.env.SLACK_CHANNEL_ID!,
      blocks: [
        {
          type: 'section',
          text: {
            type: 'mrkdwn',
            text: `🚨 *${appName}* received a negative review\n${stars} — ${review.authorName} (${review.territory})`,
          },
        },
        {
          type: 'section',
          text: { type: 'mrkdwn', text: `*${review.title}*\n${review.body}` },
        },
        {
          type: 'actions',
          elements: [{
            type: 'button',
            text: { type: 'plain_text', text: 'Open in App Store Connect' },
            url: `https://appstoreconnect.apple.com/apps/${appId}/appstore/ratings`,
          }],
        },
      ],
    });
  }
}

async function replyToReview(
  auth: AppStoreConnectAuth,
  reviewId: string,
  responseBody: string
): Promise<void> {
  // Check for existing response first — responses cannot be overwritten
  const check = await axios.get(
    `${BASE_URL}/customerReviewResponses/${reviewId}`,
    { headers: auth.getAuthHeader(), validateStatus: () => true }
  );
 
  if (check.status === 200) {
    console.log(`Review ${reviewId} already has a response, skipping`);
    return;
  }
 
  await axios.post(
    `${BASE_URL}/customerReviewResponses`,
    {
      data: {
        type: 'customerReviewResponses',
        attributes: { responseBody },
        relationships: {
          review: { data: { type: 'customerReviews', id: reviewId } },
        },
      },
    },
    { headers: { ...auth.getAuthHeader(), 'Content-Type': 'application/json' } }
  );
 
  console.log(`✅ Reply posted to review ${reviewId}`);
}

// src/report.ts — the entry point for the scheduled job
async function runMorningReport(): Promise<void> {
  const auth = new AppStoreConnectAuth(
    process.env.ASC_ISSUER_ID!,
    process.env.ASC_KEY_ID!,
    process.env.ASC_PRIVATE_KEY_PATH!
  );
 
  const yesterday = new Date(Date.now() - 86_400_000).toISOString().split('T')[0];
 
  const [salesData, reviews] = await Promise.all([
    fetchWithRetry(() =>
      fetchDailySalesReport(auth, process.env.ASC_VENDOR_NUMBER!, yesterday)
    ),
    fetchRecentReviews(auth, process.env.APP_ID!, new Date(Date.now() - 7 * 86_400_000)),
  ]);
 
  const totalRevenue = salesData.reduce((sum, r) => sum + r.developerProceeds, 0);
  const downloads = salesData.filter(r => r.productType === '7').reduce((sum, r) => sum + r.units, 0);
  const avgRating = reviews.length
    ? (reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length).toFixed(1)
    : 'N/A';
 
  await slack.chat.postMessage({
    channel: process.env.SLACK_CHANNEL_ID!,
    text: [
      `📊 *Sales Report: ${yesterday}*`,
      `💰 Developer proceeds: $${totalRevenue.toFixed(2)}`,
      `📥 Downloads: ${downloads.toLocaleString()}`,
      `⭐ Avg rating (7d): ${avgRating}`,
      `💬 New reviews (7d): ${reviews.filter(r => new Date(r.createdDate) > new Date(Date.now() - 86_400_000)).length}`,
    ].join('\n'),
  });
 
  await alertNegativeReviews(auth, process.env.APP_ID!, 'MyApp');
}
 
runMorningReport().catch(console.error);

# .github/workflows/daily-report.yml
name: Daily App Store Report
on:
  schedule:
    - cron: '0 22 * * *'  # 10 PM UTC = 7 AM JST
  workflow_dispatch:
 
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - run: echo "${{ secrets.ASC_PRIVATE_KEY }}" > ./AuthKey.p8
      - name: Run report
        env:
          ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
          ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
          ASC_PRIVATE_KEY_PATH: ./AuthKey.p8
          ASC_VENDOR_NUMBER: ${{ secrets.ASC_VENDOR_NUMBER }}
          APP_ID: ${{ secrets.APP_ID }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}
        run: npx tsx src/report.ts
      - if: always()
        run: rm -f ./AuthKey.p8

const APPS = [
  { id: '111111111', name: 'App A' },
  { id: '222222222', name: 'App B' },
  { id: '333333333', name: 'App C' },
];
 
async function runAllReports(): Promise<void> {
  // Single auth instance shared across all requests (token caching handles concurrency)
  const auth = new AppStoreConnectAuth(
    process.env.ASC_ISSUER_ID!,
    process.env.ASC_KEY_ID!,
    process.env.ASC_PRIVATE_KEY_PATH!
  );
 
  const results = await Promise.allSettled(
    APPS.map(app => alertNegativeReviews(auth, app.id, app.name))
  );
 
  results.forEach((result, i) => {
    if (result.status === 'rejected') {
      console.error(`Failed for ${APPS[i].name}:`, result.reason);
    }
  });
}

if (axios.isAxiosError(error) && error.response?.status === 404) {
  return [];   // indistinguishable from "nothing sold yesterday"
}

type SalesReportResult =
  | { state: 'ready'; records: SalesRecord[] }
  | { state: 'pending'; reportDate: string }
  | { state: 'failed'; reason: string };
 
const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
 
async function fetchSalesReport(
  auth: AppStoreConnectAuth,
  vendorNumber: string,
  date: string,
  { maxAttempts = 4, baseDelayMs = 500 } = {}
): Promise<SalesReportResult> {
  const params = new URLSearchParams({
    'filter[frequency]': 'DAILY',
    'filter[reportDate]': date,
    'filter[reportType]': 'SALES',
    'filter[vendorNumber]': vendorNumber,
    'filter[version]': '1_0',
  });
 
  let delay = baseDelayMs;
 
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const response = await axios.get(`${BASE_URL}/salesReports?${params}`, {
        headers: { ...auth.getAuthHeader(), Accept: 'application/a-gzip' },
        responseType: 'arraybuffer',
        validateStatus: () => true,
      });
 
      if (response.status === 200) {
        const tsv = (await gunzip(Buffer.from(response.data))).toString('utf8');
        return { state: 'ready', records: parseSalesTsv(tsv) };
      }
 
      // 404 means "not yet". Repeating the same request changes nothing.
      if (response.status === 404) {
        return { state: 'pending', reportDate: date };
      }
 
      // 429 tells you how long to wait. Back off only when it does not.
      if (response.status === 429) {
        const retryAfter = Number(response.headers['retry-after']);
        const wait = Number.isFinite(retryAfter) && retryAfter > 0
          ? retryAfter * 1000
          : delay + Math.floor(Math.random() * 250); // jitter spreads concurrent retries
        delay = Math.min(delay * 2, 8_000);
        await sleep(wait);
        continue;
      }
 
      return { state: 'failed', reason: `HTTP ${response.status}` };
    } catch (error) {
      if (attempt === maxAttempts) {
        return { state: 'failed', reason: (error as Error).message };
      }
      await sleep(delay);
      delay = Math.min(delay * 2, 8_000);
    }
  }
 
  return { state: 'failed', reason: 'rate limited: attempts exhausted' };
}

const result = await fetchSalesReport(auth, vendorNumber, reportDate);
 
switch (result.state) {
  case 'ready':
    await postDailySummary(result.records);
    break;
  case 'pending':
    await postPlainText(`Report for ${result.reportDate} is not generated yet. Retrying on the next run.`);
    break;
  case 'failed':
    await postPlainText(`Failed to fetch the sales report: ${result.reason}`);
    break;
}

interface WeeklyTrend {
  period: string;          // 'YYYY-Www' format
  totalRevenue: number;
  totalDownloads: number;
  avgRating: number;
  reviewCount: number;
  topCountry: string;
  topCountryRevenue: number;
}
 
async function computeWeeklyTrend(
  auth: AppStoreConnectAuth,
  vendorNumber: string,
  appId: string,
  weeksBack = 4
): Promise<WeeklyTrend[]> {
  const trends: WeeklyTrend[] = [];
 
  for (let week = 0; week < weeksBack; week++) {
    const weekStart = new Date(Date.now() - (week + 1) * 7 * 86_400_000);
    const weekDays: string[] = [];
 
    for (let d = 0; d < 7; d++) {
      const day = new Date(weekStart.getTime() + d * 86_400_000);
      weekDays.push(day.toISOString().split('T')[0]);
    }
 
    // Fetch each day in parallel (respecting rate limits with a small delay)
    const weekSalesRaw = await Promise.allSettled(
      weekDays.map((date, i) =>
        new Promise<SalesRecord[]>(resolve =>
          setTimeout(
            () => fetchDailySalesReport(auth, vendorNumber, date).then(resolve),
            i * 150 // 150ms stagger to avoid rate limiting
          )
        )
      )
    );
 
    const weekSales = weekSalesRaw
      .filter((r): r is PromiseFulfilledResult<SalesRecord[]> => r.status === 'fulfilled')
      .flatMap(r => r.value);
 
    // Country breakdown
    const byCountry = weekSales.reduce<Record<string, number>>((acc, r) => {
      acc[r.storefront] = (acc[r.storefront] || 0) + r.developerProceeds;
      return acc;
    }, {});
 
    const topCountryEntry = Object.entries(byCountry).sort(([, a], [, b]) => b - a)[0];
 
    // Reviews for this week
    const weekReviews = await fetchRecentReviews(auth, appId, weekStart);
 
    trends.push({
      period: `Week -${week + 1}`,
      totalRevenue: weekSales.reduce((s, r) => s + r.developerProceeds, 0),
      totalDownloads: weekSales.filter(r => r.productType === '7').reduce((s, r) => s + r.units, 0),
      avgRating: weekReviews.length
        ? weekReviews.reduce((s, r) => s + r.rating, 0) / weekReviews.length
        : 0,
      reviewCount: weekReviews.length,
      topCountry: topCountryEntry?.[0] ?? 'N/A',
      topCountryRevenue: topCountryEntry?.[1] ?? 0,
    });
  }
 
  return trends;
}
 
// Expected output (4 weeks of data, most recent first):
// [
//   { period: 'Week -1', totalRevenue: 127.50, totalDownloads: 843, avgRating: 4.3, reviewCount: 12, topCountry: 'JP', topCountryRevenue: 84.00 },
//   { period: 'Week -2', totalRevenue: 108.20, totalDownloads: 761, avgRating: 4.1, reviewCount: 8, topCountry: 'JP', topCountryRevenue: 71.50 },
//   ...
// ]

interface AppLocalization {
  locale: string;       // e.g., 'en-US', 'ja-JP', 'de-DE'
  name: string;         // App name (max 30 chars on iOS)
  subtitle: string;     // Subtitle (max 30 chars)
  description: string;  // Full description
  keywords: string;     // Comma-separated, max 100 chars total
  promotionalText: string; // Updated without a new submission (max 170 chars)
}
 
async function updateAppLocalization(
  auth: AppStoreConnectAuth,
  appId: string,
  localization: AppLocalization
): Promise<void> {
  // First, fetch the existing localization resource ID
  const listResponse = await axios.get(
    `${BASE_URL}/apps/${appId}/appStoreVersions?filter[platform]=IOS&filter[appStoreState]=PREPARE_FOR_SUBMISSION&limit=1`,
    { headers: auth.getAuthHeader() }
  );
 
  const versionId = listResponse.data.data?.[0]?.id;
  if (!versionId) {
    throw new Error('No version in PREPARE_FOR_SUBMISSION state. Create a new version first.');
  }
 
  // Get the localization ID for this locale
  const locResponse = await axios.get(
    `${BASE_URL}/appStoreVersions/${versionId}/appStoreVersionLocalizations?filter[locale]=${localization.locale}`,
    { headers: auth.getAuthHeader() }
  );
 
  const locId = locResponse.data.data?.[0]?.id;
 
  if (locId) {
    // Update existing localization
    await axios.patch(
      `${BASE_URL}/appStoreVersionLocalizations/${locId}`,
      {
        data: {
          type: 'appStoreVersionLocalizations',
          id: locId,
          attributes: {
            description: localization.description,
            keywords: localization.keywords,
            promotionalText: localization.promotionalText,
          },
        },
      },
      { headers: { ...auth.getAuthHeader(), 'Content-Type': 'application/json' } }
    );
    console.log(`✅ Updated ${localization.locale} localization`);
  } else {
    // Create new localization for this locale
    await axios.post(
      `${BASE_URL}/appStoreVersionLocalizations`,
      {
        data: {
          type: 'appStoreVersionLocalizations',
          attributes: {
            locale: localization.locale,
            name: localization.name,
            subtitle: localization.subtitle,
            description: localization.description,
            keywords: localization.keywords,
          },
          relationships: {
            appStoreVersion: { data: { type: 'appStoreVersions', id: versionId } },
          },
        },
      },
      { headers: { ...auth.getAuthHeader(), 'Content-Type': 'application/json' } }
    );
    console.log(`✅ Created ${localization.locale} localization`);
  }
}

interface ReleaseRatingCorrelation {
  versionString: string;
  releaseDate: string;
  avgRatingAfterRelease: number; // average rating for reviews posted in the 14 days after release
  reviewCount: number;
  sentiment: 'positive' | 'neutral' | 'negative';
}
 
async function analyzeReleaseSentiment(
  auth: AppStoreConnectAuth,
  appId: string
): Promise<ReleaseRatingCorrelation[]> {
  // Fetch version history
  const versionsResponse = await axios.get(
    `${BASE_URL}/apps/${appId}/appStoreVersions?filter[platform]=IOS&limit=10&sort=-createdDate`,
    { headers: auth.getAuthHeader() }
  );
 
  const versions = versionsResponse.data.data.map((v: any) => ({
    versionString: v.attributes.versionString,
    releaseDate: v.attributes.earliestReleaseDate || v.attributes.createdDate,
  }));
 
  // Fetch all reviews once, then filter by date for each version
  const allReviews = await fetchRecentReviews(
    auth,
    appId,
    new Date(Date.now() - 90 * 86_400_000) // Last 90 days
  );
 
  return versions.map(version => {
    const releaseDate = new Date(version.releaseDate);
    const windowEnd = new Date(releaseDate.getTime() + 14 * 86_400_000);
 
    const windowReviews = allReviews.filter(r => {
      const d = new Date(r.createdDate);
      return d >= releaseDate && d <= windowEnd;
    });
 
    const avgRating = windowReviews.length
      ? windowReviews.reduce((sum, r) => sum + r.rating, 0) / windowReviews.length
      : 0;
 
    return {
      versionString: version.versionString,
      releaseDate: version.releaseDate,
      avgRatingAfterRelease: Math.round(avgRating * 10) / 10,
      reviewCount: windowReviews.length,
      sentiment: avgRating >= 4.0 ? 'positive' : avgRating >= 3.0 ? 'neutral' : 'negative',
    };
  });
}
 
// Expected output:
// [
//   { versionString: '2.4.1', releaseDate: '2026-04-10', avgRatingAfterRelease: 4.6, reviewCount: 18, sentiment: 'positive' },
//   { versionString: '2.4.0', releaseDate: '2026-03-28', avgRatingAfterRelease: 2.8, reviewCount: 31, sentiment: 'negative' },
//   { versionString: '2.3.5', releaseDate: '2026-03-10', avgRatingAfterRelease: 4.2, reviewCount: 9, sentiment: 'positive' },
// ]