Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AppStoreServerAPI
✓ import { AppStoreServerAPI } from 'app-store-server-api'
✗ const AppStoreServerAPI = require('app-store-server-api').AppStoreServerAPI
While CommonJS `require` can still work in some setups, native ESM `import` is the recommended and standard approach, especially after TypeScript target was switched to ES6 in v0.17.0.
Environment
✓ import { Environment } from 'app-store-server-api'
✗ import { ENVIRONMENT } from 'app-store-server-api'
The `Environment` enum is a named export. Ensure correct casing and named import syntax.
decodeTransaction
✓ import { decodeTransaction } from 'app-store-server-api'
✗ import decodeTransaction from 'app-store-server-api/decodeTransaction'
Decoding helpers like `decodeTransaction`, `decodeRenewalInfo`, and `decodeTransactions` are named exports from the main package entry point.
isDecodedNotificationSummaryPayload
✓ import { isDecodedNotificationSummaryPayload } from 'app-store-server-api'
✗ import { isdecodedNotificationSummaryPayload } from 'app-store-server-api'
A typo was fixed in v0.14.1, renaming `isdecodedNotificationSummaryPayload` to `isDecodedNotificationSummaryPayload`. Ensure you use the corrected name.
This quickstart demonstrates how to initialize the App Store Server API client and fetch a user's recent auto-renewable transaction history, including decoding and verifying the signed transaction data. It highlights the use of environment variables for sensitive API credentials.
import { AppStoreServerAPI, Environment, ProductTypeParameter, SortParameter } from 'app-store-server-api';
// Ensure these are loaded from secure environment variables in a production setup
const KEY = process.env.APPLE_PRIVATE_KEY ??
`-----BEGIN PRIVATE KEY-----
MHcCAQEEIPWH5lyoG7Wbzv71ntF6jNvFwwJLKYmPWN/KBD4qJfMcoAoGCCqGSM49
AwEHoUQDQgAEMOlUa/hmyAPU/RUBds6xzDO8QNrTFhFwzm8E4wxDnSAx8R9WOMnD
cVGdtnbLFIdLk8g4S7oAfV/gGILKuc+Vqw==
-----END PRIVATE KEY-----`;
const KEY_ID = process.env.APPLE_KEY_ID ?? "ABCD123456";
const ISSUER_ID = process.env.APPLE_ISSUER_ID ?? "91fa5999-7b54-4363-a2a8-265363fa6cbe";
const APP_BUNDLE_ID = process.env.APPLE_APP_BUNDLE_ID ?? "com.yourcompany.app";
const api = new AppStoreServerAPI(
KEY, KEY_ID, ISSUER_ID, APP_BUNDLE_ID, Environment.Sandbox // Use Environment.Production for live apps
);
async function getRecentPurchases(originalTransactionId: string) {
try {
const response = await api.getTransactionHistory(originalTransactionId, {
productType: ProductTypeParameter.AutoRenewable,
sort: SortParameter.Descending,
limit: 20 // Fetch up to 20 transactions
});
// Decoding verifies the signature and provides typed access to transaction data.
const transactions = await api.decodeTransactions(response.signedTransactions);
console.log(`Found ${transactions.length} transactions for ${originalTransactionId}:`);
for (const transaction of transactions) {
console.log(` Transaction ID: ${transaction.transactionId}, Product ID: ${transaction.productId}, Purchase Date: ${new Date(transaction.purchaseDate).toISOString()}`);
// Further processing with transaction data...
}
if (response.hasMore) {
console.log('More transactions available. Consider fetching with response.revision for next page.');
}
} catch (error) {
console.error('Error fetching transaction history:', error);
}
}
// Example usage (replace with a real originalTransactionId from your system)
// In a real application, you'd get this from your database or client.
const exampleOriginalTransactionId = "123456789012345";
getRecentPurchases(exampleOriginalTransactionId);
Errors
Common errors & fixes
Error: Unexpected status code: 202 Accepted
Older versions of the client did not explicitly handle HTTP 202 (Accepted) as a successful response for certain API calls, leading to errors.
fixUpgrade `app-store-server-api` to version `0.17.1` or newer, which includes handling for the 202 status code.
SyntaxError: Cannot use import statement outside a module or ReferenceError: require is not defined
Attempting to use ES module `import` syntax in a CommonJS context or `require()` in an ES module context, especially prevalent after the v0.17.0 TypeScript target change to ES6.
fixEnsure your project is configured for ES modules (e.g., by setting `"type": "module"` in `package.json` or using `.mjs` file extension) and use `import` statements. Alternatively, if sticking to CommonJS, explicitly use `require()` syntax with `.cjs` file extension or configure `tsconfig.json` for CommonJS output.
Error: API request failed with status 401: NOT_AUTHORIZED
The JWT (JSON Web Token) used for authentication is invalid, expired, or the credentials (Key ID, Issuer ID, Bundle ID, Private Key) are incorrect.
fixDouble-check your API Key, Key ID, Issuer ID, and App Bundle ID for accuracy. Ensure the private key is correctly formatted and the JWT generation logic is sound. Verify that the JWT is not expired and is signed with the correct algorithm (ES256).
Audit
Dependencies
No dependency data recorded yet.