@gpc-cli/api

Typed Google Play Developer API v3 client for TypeScript. Part of GPC.

234 endpoints across edits, releases, tracks, listings, subscriptions, in-app products, purchases, reviews, vitals, reports, users, testers, and Managed Google Play private app publishing (Play Custom App Publishing API, v0.9.64+ — first Android publishing SDK to support this). Built-in rate limiting, retry logic, resumable uploads, and pagination.

Install

npm install @gpc-cli/api @gpc-cli/auth

Quick Start

import { createApiClient } from "@gpc-cli/api";
import { resolveAuth } from "@gpc-cli/auth";

const auth = await resolveAuth({
  serviceAccountPath: "./service-account.json",
});
const client = createApiClient({ auth });

const edit = await client.edits.insert("com.example.app");
const tracks = await client.tracks.list("com.example.app", edit.id);
console.log(tracks);
await client.edits.delete("com.example.app", edit.id);

Client Factories

| Factory | Purpose | | -------------------------------- | ---------------------------------------------------------------- | | createApiClient(options) | Core Play API: apps, releases, listings, monetization, purchases | | createReportingClient(options) | Vitals, crash rates, ANR, error reporting | | createUsersClient(options) | Developer account users and permission grants | | createHttpClient(options) | Low-level HTTP with auth, retry, and rate limiting |

const options: ApiClientOptions = {
  auth, // Required: { getAccessToken(): Promise<string> }
  maxRetries: 3, // Default retry count
  timeout: 30_000, // Request timeout in ms
  onRetry: (entry) => console.warn(`Retry #${entry.attempt}`),
  lifecycleHooks: {
    beforeRequest: (event) => console.log(event.method, event.path),
    afterResponse: (_event, response) => console.log(response.status, response.durationMs),
  },
};

Request lifecycle observers

ApiClientOptions.lifecycleHooks observes every transport attempt, including retries, uploads, and downloads. Events contain the HTTP method, a query-free path with purchase credentials redacted, and timing/status metadata. Observer errors are isolated and never change the API operation result. When transport fails before any HTTP response, afterResponse receives status: 0 and ok: false.

Use fetchWithApiLifecycle() for standalone requests that should share the same observer contract. setDefaultApiLifecycleHooks() sets process-wide defaults used only when a client has no explicit hooks; it is primarily intended for CLI composition roots.

import { fetchWithApiLifecycle, setDefaultApiLifecycleHooks } from "@gpc-cli/api";

setDefaultApiLifecycleHooks({
  beforeRequest: (event) => console.log(event.method, event.path),
});
const response = await fetchWithApiLifecycle(
  "https://example.test/status",
  { method: "GET" },
  "/status",
);

Common Workflows

Upload and release

const edit = await client.edits.insert("com.example.app");
await client.bundles.upload("com.example.app", edit.id, "./app.aab");
await client.tracks.update("com.example.app", edit.id, "beta", {
  versionCodes: ["42"],
  status: "completed",
  releaseNotes: [{ language: "en-US", text: "Bug fixes" }],
});
await client.edits.commit("com.example.app", edit.id);

Query crash rates

import { createReportingClient } from "@gpc-cli/api";

const reporting = createReportingClient({ auth });
const crashes = await reporting.queryMetricSet("com.example.app", "crashRateMetricSet", {
  metrics: ["crashRate", "userPerceivedCrashRate"],
  timelineSpec: {
    aggregationPeriod: "DAILY",
    startTime: { year: 2026, month: 1, day: 1 },
    endTime: { year: 2026, month: 3, day: 1 },
  },
});

Manage subscriptions

const { subscriptions } = await client.subscriptions.list("com.example.app");
await client.subscriptions.activateBasePlan("com.example.app", "premium_monthly", "p1m");

Verify purchases

const purchase = await client.purchases.getProduct("com.example.app", "coins_100", token);
await client.purchases.acknowledgeProduct("com.example.app", "coins_100", token);

All API Modules

| Module | Methods | | ----------------------------- | ----------------------------------------------------------------------------------------------------------- | | client.edits | insert, get, validate, commit, delete | | client.details | get, update, patch | | client.bundles | upload, list | | client.apks | upload, list | | client.tracks | list, get, update, patch, create, delete | | client.releases | get, update | | client.countryAvailability | get, list | | client.listings | list, get, update, delete, deleteAll | | client.images | list, upload, delete, deleteAll | | client.subscriptions | list, get, create, patch, archive, activate/deactivate base plans and offers | | client.inappproducts | list, get, create, update, delete, batchGet, batchUpdate, batchDelete | | client.oneTimeProducts | list, get, create, patch, delete, batchGet, batchUpdate, batchDelete, activateOffer, deactivateOffer | | client.purchases | getProduct, acknowledgeProduct, getSubscriptionV2, revokeSubscriptionV2, refund, listVoided, consumeProduct | | client.orders | get, refund | | client.reviews | list, get, reply | | client.testers | get, update | | client.reports | list | | client.monetization | convertRegionPrices | | client.deobfuscation | upload | | client.expansionFiles | get, update, patch, upload | | client.dataSafety | update | | client.deviceTiers | list, get, create | | client.internalAppSharing | uploadBundle, uploadApk | | client.generatedApks | list, download | | client.systemApks | list, variants | | client.externalTransactions | create, get, refund | | client.appRecovery | create, deploy, cancel, list | | client.appSigning | enroll, rotateKey (self-hosted Google Cloud KMS keys only — advanced) | | reporting.* | queryMetricSet, getAnomalies, searchErrorIssues, searchErrorReports | | users.* | list, get, create, patch, delete, listGrants, createGrant, patchGrant, deleteGrant |

Supported metric sets (pass to reporting.queryMetricSet): crashRateMetricSet, anrRateMetricSet, lmkRateMetricSet, excessiveWakeupRateMetricSet, slowStartRateMetricSet, slowRenderingRateMetricSet, stuckBackgroundWakelockRateMetricSet, errorCountMetricSet.

Pagination

import { paginateAll } from "@gpc-cli/api";

const allReviews = await paginateAll(async (pageToken) => {
  const response = await client.reviews.list("com.example.app", {
    token: pageToken,
    maxResults: 100,
  });
  return {
    items: response.reviews,
    nextPageToken: response.tokenPagination?.nextPageToken,
  };
});

Error Handling

API errors throw PlayApiError with a code, HTTP status, and actionable suggestion. Retries are automatic for 429 and 5xx with exponential backoff and jitter.

import { PlayApiError } from "@gpc-cli/api";

try {
  await client.tracks.get("com.example.app", editId, "production");
} catch (error) {
  if (error instanceof PlayApiError) {
    console.error(error.code); // "API_NOT_FOUND"
    console.error(error.statusCode); // 404
    console.error(error.suggestion); // actionable fix
  }
}

Type Exports

All Google Play API types are exported:

import type {
  PlayApiClient,
  ReportingApiClient,
  UsersApiClient,
  ApiClientOptions,
  ApiLifecycleHooks,
  ApiRequestEvent,
  ApiResponseEvent,
  Track,
  Release,
  ReleaseStatus,
  Bundle,
  Listing,
  Subscription,
  BasePlan,
  SubscriptionOffer,
  InAppProduct,
  Review,
  ProductPurchase,
  SubscriptionPurchaseV2,
  VoidedPurchase,
  MetricSetQuery,
  MetricSetResponse,
  ErrorIssue,
  User,
  Grant,
  AppLevelPermission,
  DeveloperLevelPermission,
  SubscriptionState,
  OneTimeOfferState,
  OneTimeProductAvailability,
  ImageType,
  Money,
} from "@gpc-cli/api";

Documentation

• Full documentation
• SDK usage guide
• API coverage map

Licensing

MIT-licensed open source and free to use. Source code is on GitHub at yasserstudio/gpc.