@gpc-cli/api 1.0.27 → 1.0.28

package/README.md

@@ -2,7 +2,7 @@
 
 Typed Google Play Developer API v3 client for TypeScript. Part of [GPC](https://github.com/yasserstudio/gpc).
 
-The entire Google Play Developer API in one typed client — 204 endpoints covering edits, releases, tracks, listings, images, subscriptions, in-app products, purchases, reviews, vitals, reports, users, and testers. Built-in rate limiting, retry logic, and pagination. Works with your existing service account — no new credentials required.
+208 endpoints across edits, releases, tracks, listings, subscriptions, in-app products, purchases, reviews, vitals, reports, users, and testers. Built-in rate limiting, retry logic, and pagination.
 
 ## Install
 
@@ -19,204 +19,53 @@ import { resolveAuth } from "@gpc-cli/auth";
 const auth = await resolveAuth({
   serviceAccountPath: "./service-account.json",
 });
-
 const client = createApiClient({ auth });
 
-// List all tracks
 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                 |
-
-All factories accept `ApiClientOptions`:
+| 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 |
 
 ```typescript
-import type { ApiClientOptions } from "@gpc-cli/api";
-
 const options: ApiClientOptions = {
-  auth, // Required: { getAccessToken(): Promise<string> }
-  maxRetries: 3, // Default retry count
-  timeout: 30_000, // Request timeout in ms
-  rateLimiter: undefined, // Optional custom rate limiter
-  onRetry: (entry) => console.warn(`Retry #${entry.attempt}: ${entry.error}`),
+  auth,                    // Required: { getAccessToken(): Promise<string> }
+  maxRetries: 3,           // Default retry count
+  timeout: 30_000,         // Request timeout in ms
+  onRetry: (entry) => console.warn(`Retry #${entry.attempt}`),
 };
 ```
 
-## API Modules
-
-### Edits
-
-Every modification to app metadata, tracks, or listings requires an edit session.
-
-```typescript
-const edit = await client.edits.insert("com.example.app");
-
-// ... make changes within the edit ...
-
-await client.edits.validate("com.example.app", edit.id);
-await client.edits.commit("com.example.app", edit.id);
-```
+## Common Workflows
 
-### Bundles
+### Upload and release
 
 ```typescript
 const edit = await client.edits.insert("com.example.app");
-const bundle = await client.bundles.upload("com.example.app", edit.id, "./app.aab");
-const bundles = await client.bundles.list("com.example.app", edit.id);
-await client.edits.commit("com.example.app", edit.id);
-```
-
-### Tracks & Releases
-
-```typescript
-const edit = await client.edits.insert("com.example.app");
-
-const tracks = await client.tracks.list("com.example.app", edit.id);
-const production = await client.tracks.get("com.example.app", edit.id, "production");
-
-await client.tracks.update("com.example.app", edit.id, "production", {
+await client.bundles.upload("com.example.app", edit.id, "./app.aab");
+await client.tracks.update("com.example.app", edit.id, "beta", {
   versionCodes: ["42"],
-  status: "inProgress",
-  userFraction: 0.1,
+  status: "completed",
   releaseNotes: [{ language: "en-US", text: "Bug fixes" }],
 });
-
-await client.edits.commit("com.example.app", edit.id);
-```
-
-### Listings
-
-```typescript
-const edit = await client.edits.insert("com.example.app");
-
-const listings = await client.listings.list("com.example.app", edit.id);
-const en = await client.listings.get("com.example.app", edit.id, "en-US");
-
-await client.listings.update("com.example.app", edit.id, "en-US", {
-  title: "My App",
-  shortDescription: "A great app",
-  fullDescription: "Full description here...",
-});
-
-await client.edits.commit("com.example.app", edit.id);
-```
-
-### Images
-
-```typescript
-const edit = await client.edits.insert("com.example.app");
-
-const screenshots = await client.images.list(
-  "com.example.app",
-  edit.id,
-  "en-US",
-  "phoneScreenshots",
-);
-
-await client.images.upload("com.example.app", edit.id, "en-US", "featureGraphic", "./feature.png");
-
-await client.images.deleteAll("com.example.app", edit.id, "en-US", "phoneScreenshots");
 await client.edits.commit("com.example.app", edit.id);
 ```
 
-Image types: `phoneScreenshots`, `sevenInchScreenshots`, `tenInchScreenshots`, `tvScreenshots`, `wearScreenshots`, `icon`, `featureGraphic`, `tvBanner`.
-
-### Subscriptions
-
-```typescript
-const { subscriptions } = await client.subscriptions.list("com.example.app");
-const sub = await client.subscriptions.get("com.example.app", "premium_monthly");
-
-await client.subscriptions.activateBasePlan("com.example.app", "premium_monthly", "p1m");
-await client.subscriptions.deactivateBasePlan("com.example.app", "premium_monthly", "p1m");
-```
-
-### Subscription Offers
-
-```typescript
-const { subscriptionOffers } = await client.subscriptions.listOffers(
-  "com.example.app",
-  "premium_monthly",
-  "p1m",
-);
-
-const offer = await client.subscriptions.getOffer(
-  "com.example.app",
-  "premium_monthly",
-  "p1m",
-  "intro_offer",
-);
-
-await client.subscriptions.activateOffer(
-  "com.example.app",
-  "premium_monthly",
-  "p1m",
-  "intro_offer",
-);
-```
-
-### In-App Products
-
-```typescript
-const { inappproduct } = await client.inappproducts.list("com.example.app");
-const product = await client.inappproducts.get("com.example.app", "coins_100");
-
-await client.inappproducts.create("com.example.app", {
-  sku: "coins_500",
-  status: "active",
-  purchaseType: "managedUser",
-  defaultPrice: { currencyCode: "USD", units: "4", nanos: 990_000_000 },
-});
-```
-
-### Purchases
-
-```typescript
-// Verify a product purchase
-const purchase = await client.purchases.getProduct("com.example.app", "coins_100", purchaseToken);
-
-// Acknowledge it
-await client.purchases.acknowledgeProduct("com.example.app", "coins_100", purchaseToken);
-
-// Verify a subscription (v2)
-const sub = await client.purchases.getSubscriptionV2("com.example.app", purchaseToken);
-
-// List voided purchases
-const { voidedPurchases } = await client.purchases.listVoided("com.example.app", {
-  startTime: "1700000000000",
-  maxResults: 100,
-});
-```
-
-### Reviews
-
-```typescript
-const { reviews } = await client.reviews.list("com.example.app", { maxResults: 50 });
-const review = await client.reviews.get("com.example.app", reviewId);
-await client.reviews.reply("com.example.app", reviewId, "Thanks for the feedback!");
-```
-
-### Vitals & Error Reporting
-
-Uses a separate client that targets the Play Developer Reporting API.
+### Query crash rates
 
 ```typescript
 import { createReportingClient } from "@gpc-cli/api";
 
 const reporting = createReportingClient({ auth });
-
-// Query crash rate
 const crashes = await reporting.queryMetricSet("com.example.app", "crashRateMetricSet", {
   metrics: ["crashRate", "userPerceivedCrashRate"],
   timelineSpec: {
@@ -225,75 +74,52 @@ const crashes = await reporting.queryMetricSet("com.example.app", "crashRateMetr
     endTime: { year: 2026, month: 3, day: 1 },
   },
 });
-
-// Detect anomalies
-const { anomalies } = await reporting.getAnomalies("com.example.app");
-
-// Search error issues
-const { errorIssues } = await reporting.searchErrorIssues("com.example.app");
 ```
 
-Available metric sets: `crashRateMetricSet`, `anrRateMetricSet`, `excessiveWakeupRateMetricSet`, `stuckBackgroundWakelockRateMetricSet`, `slowStartRateMetricSet`, `slowRenderingRateMetricSet`, `errorCountMetricSet`.
-
-### Reports
+### Manage subscriptions
 
 ```typescript
-const { reports } = await client.reports.list("com.example.app", "earnings", 2026, 2);
-```
-
-Report types: `earnings`, `sales`, `estimated_sales`, `installs`, `crashes`, `ratings`, `reviews`, `store_performance`, `subscriptions`, `play_balance`.
-
-### Users & Grants
-
-Uses a separate client for developer account management.
-
-```typescript
-import { createUsersClient } from "@gpc-cli/api";
-
-const users = createUsersClient({ auth });
-
-const { users: devUsers } = await users.list(developerId);
-const user = await users.get(developerId, userId);
-
-await users.create(developerId, {
-  email: "dev@example.com",
-  developerAccountPermission: ["CAN_MANAGE_PUBLIC_APKS", "CAN_REPLY_TO_REVIEWS"],
-});
-```
-
-### Testers
-
-```typescript
-const edit = await client.edits.insert("com.example.app");
-const testers = await client.testers.get("com.example.app", edit.id, "internal");
-
-await client.testers.update("com.example.app", edit.id, "internal", {
-  googleGroups: ["testers@example.com"],
-});
-
-await client.edits.commit("com.example.app", edit.id);
-```
-
-### Monetization
-
-```typescript
-const { convertedRegionPrices } = await client.monetization.convertRegionPrices("com.example.app", {
-  price: { currencyCode: "USD", units: "9", nanos: 990_000_000 },
-});
+const { subscriptions } = await client.subscriptions.list("com.example.app");
+await client.subscriptions.activateBasePlan("com.example.app", "premium_monthly", "p1m");
 ```
 
-### Deobfuscation
-
-```typescript
-const edit = await client.edits.insert("com.example.app");
-await client.deobfuscation.upload("com.example.app", edit.id, 42, "./mapping.txt");
-await client.edits.commit("com.example.app", edit.id);
-```
+### Verify purchases
+
+```typescript
+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.bundles` | upload, list |
+| `client.tracks` | list, get, update |
+| `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 |
+| `client.purchases` | getProduct, acknowledgeProduct, getSubscriptionV2, revokeSubscription, refund, listVoided |
+| `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` | get, update |
+| `client.deviceTiers` | list, get, create |
+| `client.internalSharing` | uploadBundle, uploadApk |
+| `client.generatedApks` | list, download |
+| `client.externalTransactions` | create, get, refund |
+| `client.appRecovery` | create, deploy, cancel, list |
+| `reporting.*` | queryMetricSet, getAnomalies, searchErrorIssues, searchErrorReports |
+| `users.*` | list, get, create, patch, delete, listGrants, createGrant, patchGrant, deleteGrant |
 
 ## Pagination
 
-Built-in helpers for paginated endpoints:
-
 ```typescript
 import { paginateAll } from "@gpc-cli/api";
 
@@ -309,42 +135,9 @@ const allReviews = await paginateAll(async (pageToken) => {
 });
 ```
 
-## Type Exports
-
-All Google Play API types are exported for use in your own code:
-
-```typescript
-import type {
-  PlayApiClient,
-  ReportingApiClient,
-  UsersApiClient,
-  ApiClientOptions,
-  Track,
-  Release,
-  ReleaseStatus,
-  Bundle,
-  Listing,
-  Subscription,
-  BasePlan,
-  SubscriptionOffer,
-  InAppProduct,
-  Review,
-  ProductPurchase,
-  SubscriptionPurchaseV2,
-  VoidedPurchase,
-  MetricSetQuery,
-  MetricSetResponse,
-  ErrorIssue,
-  User,
-  Grant,
-  ImageType,
-  Money,
-} from "@gpc-cli/api";
-```
-
 ## Error Handling
 
-API errors throw `ApiError` with a code, HTTP status, and actionable suggestion:
+API errors throw `ApiError` with a code, HTTP status, and actionable suggestion. Retries are automatic for 429 and 5xx with exponential backoff and jitter.
 
 ```typescript
 import { ApiError } from "@gpc-cli/api";
@@ -353,20 +146,33 @@ try {
   await client.tracks.get("com.example.app", editId, "production");
 } catch (error) {
   if (error instanceof ApiError) {
-    console.error(error.code); // e.g. "API_NOT_FOUND"
-    console.error(error.statusCode); // e.g. 404
+    console.error(error.code);       // "API_NOT_FOUND"
+    console.error(error.statusCode); // 404
     console.error(error.suggestion); // actionable fix
-    console.error(error.toJSON()); // structured error object
   }
 }
 ```
 
-Retries are automatic for 429 (rate limit) and 5xx errors with exponential backoff and jitter.
+## Type Exports
+
+All Google Play API types are exported:
+
+```typescript
+import type {
+  PlayApiClient, ReportingApiClient, UsersApiClient, ApiClientOptions,
+  Track, Release, ReleaseStatus, Bundle, Listing,
+  Subscription, BasePlan, SubscriptionOffer, InAppProduct,
+  Review, ProductPurchase, SubscriptionPurchaseV2, VoidedPurchase,
+  MetricSetQuery, MetricSetResponse, ErrorIssue,
+  User, Grant, ImageType, Money,
+} from "@gpc-cli/api";
+```
 
 ## Documentation
 
 - [Full documentation](https://yasserstudio.github.io/gpc/)
-- [SDK usage guide](https://yasserstudio.github.io/gpc/advanced/sdk-usage.html)
+- [SDK usage guide](https://yasserstudio.github.io/gpc/advanced/sdk-usage)
+- [API coverage map](https://yasserstudio.github.io/gpc/reference/api-coverage)
 
 ## License
 

package/dist/index.js

@@ -1312,6 +1312,14 @@ function createApiClient(options) {
           filePath,
           "application/octet-stream"
         );
+        if (!data.expansionFile) {
+          throw new PlayApiError(
+            "Upload succeeded but no expansion file data returned",
+            "API_EMPTY_RESPONSE",
+            200,
+            "This is unexpected. Retry the upload or contact Google Play support if the issue persists."
+          );
+        }
         return data.expansionFile;
       }
     },