@perdieminc/mobile-app-versions

Fetch production app versions from Google Play Store and Apple App Store.

Installation

npm install @perdieminc/mobile-app-versions

Quick Start

const MobileAppVersions = require('@perdieminc/mobile-app-versions');

const client = new MobileAppVersions({
  gcpKey: process.env.GCP_KEY // Required for Android lookups
});

// Get iOS version
const iosVersion = await client.getIosVersion('com.example.app');
console.log(iosVersion); // "1.2.3"

// Get Android version
const androidVersion = await client.getAndroidVersion('com.example.app');
console.log(androidVersion); // "1.2.3"

// Get both versions
const versions = await client.getVersions('com.example.app');
console.log(versions);
// { ios: "1.2.3", android: "1.2.3" }

API Reference

Constructor

const client = new MobileAppVersions(options);

Option	Type	Description	Default
gcpKey	string	Base64-encoded GCP service account JSON key	process.env.GCP_KEY
googleAuthUrl	string	Google OAuth token URL	https://oauth2.googleapis.com/token
itunesUrl	string	iTunes lookup API URL	https://itunes.apple.com/lookup
androidPublisherUrl	string	Android Publisher API URL	https://androidpublisher.googleapis.com/androidpublisher/v3/applications

Methods

getIosVersion(bundleId)

Fetches the production version of an iOS app from the App Store.

const version = await client.getIosVersion('com.example.app');
// Returns: "1.2.3"

getAndroidVersion(bundleId)

Fetches the production version of an Android app from Google Play.

const version = await client.getAndroidVersion('com.example.app');
// Returns: "1.2.3"

getVersions(bundleId)

Fetches both iOS and Android versions for a single bundle ID.

const result = await client.getVersions('com.example.app');
// Returns: { ios: "1.2.3", android: "1.2.3" }
// If one fails: { ios: "1.2.3", android: null, errors: { android: "error message" } }

getVersionsForMultipleBundles(bundleIds)

Fetches versions for multiple bundle IDs.

const results = await client.getVersionsForMultipleBundles([
  'com.app.one',
  'com.app.two'
]);
// Returns:
// {
//   "com.app.one": { ios: "1.0.0", android: "1.0.0" },
//   "com.app.two": { ios: "2.0.0", android: "2.0.0" }
// }

Convenience Methods

// Shorthand for getIosVersion
await client.ios('com.example.app');

// Shorthand for getAndroidVersion
await client.android('com.example.app');

Factory Function

const { createClient } = require('@perdieminc/mobile-app-versions');

const client = createClient({ gcpKey: '...' });

Configuration

Environment Variables

You can configure the module using environment variables instead of constructor options:

Variable	Description
GCP_KEY	Base64-encoded GCP service account JSON key
GOOGLE_AUTH_URL	Google OAuth token URL
ITUNES_URL	iTunes lookup API URL
ANDROID_PUBLISHER_URL	Android Publisher API URL

GCP Service Account Setup (for Android)

To fetch Android app versions, you need a Google Cloud Platform service account with access to the Google Play Developer API:

1. Go to the Google Cloud Console
2. Create or select a project
3. Enable the Google Play Android Developer API
4. Create a service account with appropriate permissions
5. Download the JSON key file
6. Base64 encode the JSON key:

   base64 -i service-account.json

7. Set the encoded string as GCP_KEY

The service account must also be linked to your Google Play Console:

1. Go to Google Play Console
2. Navigate to Settings > API access
3. Link your Google Cloud project
4. Grant the service account access to your apps

Error Handling

The module throws descriptive errors for common issues:

try {
  const version = await client.getIosVersion('invalid.bundle.id');
} catch (error) {
  console.error(error.message);
  // "No iOS app found for bundleId: invalid.bundle.id"
}

When using getVersions(), errors are captured in the response instead of throwing:

const result = await client.getVersions('com.example.app');
if (result.errors?.ios) {
  console.error('iOS lookup failed:', result.errors.ios);
}
if (result.errors?.android) {
  console.error('Android lookup failed:', result.errors.android);
}

Testing

# Run unit tests
npm test

# Run integration tests (requires network access)
npm run test:integration

Requirements

Built for Node 22.x but can work on node 18.x

Deployment

When pushing a git tag it will trigger a Github action that will deploy the package to NPM

License

ISC