@gpc-cli/api 1.0.29 → 1.0.31

package/README.md

@@ -2,7 +2,7 @@
 
 Typed Google Play Developer API v3 client for TypeScript. Part of [GPC](https://github.com/yasserstudio/gpc).
 
-215 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.
+216 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.56+ — first Android publishing SDK to support this). Built-in rate limiting, retry logic, resumable uploads, and pagination.
 
 ## Install
 
@@ -192,6 +192,6 @@ import type {
 - [SDK usage guide](https://yasserstudio.github.io/gpc/advanced/sdk-usage)
 - [API coverage map](https://yasserstudio.github.io/gpc/reference/api-coverage)
 
-## License
+## Licensing
 
-MIT
+Free to use. Source code is on GitHub at [yasserstudio/gpc](https://github.com/yasserstudio/gpc).

package/dist/index.d.ts

@@ -479,8 +479,6 @@ interface SubscriptionPurchaseV2 {
     subscriptionState: string;
     acknowledgementState?: string;
     linkedPurchaseToken?: string;
-    /** Current offer phase: free trial, introductory price, proration, or base plan price. (Jan 2026) */
-    offerPhase?: string;
     /** Resubscription context when purchase originates from Play Store. (Nov 2025) */
     outOfAppPurchaseContext?: {
         externalTransactionToken?: string;
@@ -550,8 +548,13 @@ interface SubscriptionPurchaseLineItem {
             offerId?: string;
         };
     };
-    /** Current offer phase identifier. (Jan 2026) */
-    offerPhase?: string;
+    /** Current offer phase (union field — exactly one set). (Jan 2026) */
+    offerPhase?: {
+        basePrice?: Record<string, unknown>;
+        freeTrial?: Record<string, unknown>;
+        introductoryPrice?: Record<string, unknown>;
+        proratedPeriod?: Record<string, unknown>;
+    };
 }
 interface SubscriptionPurchase {
     startTimeMillis: string;
@@ -659,9 +662,39 @@ interface ProductPurchaseLineItem {
         offerTags?: string[];
     };
 }
+/**
+ * Request body for purchases.subscriptions.acknowledge.
+ * externalAccountId is used to associate a resubscription purchase with a
+ * user identifier. (Nov 2025)
+ */
+interface AcknowledgeSubscriptionRequest {
+    developerPayload?: string;
+    externalAccountId?: string;
+}
 interface SubscriptionsV2CancelRequest {
     cancellationType?: string;
 }
+/**
+ * Request body for purchases.subscriptionsv2.revoke.
+ * revocationContext is a union — exactly one of fullRefund, proratedRefund,
+ * or itemBasedRefund should be set. itemBasedRefund targets a single add-on
+ * product by productId. (May 2025)
+ */
+interface RevokeSubscriptionV2Request {
+    revocationContext?: {
+        fullRefund?: Record<string, never>;
+        proratedRefund?: Record<string, never>;
+        itemBasedRefund?: {
+            productId: string;
+        };
+    };
+}
+/**
+ * Request body for purchases.subscriptionsv2.defer.
+ * For subscriptions with add-ons, the billing date of all line items is
+ * deferred together server-side — no per-line-item field is required in
+ * the request. (Jan 2026)
+ */
 interface SubscriptionsV2DeferRequest {
     deferralInfo: {
         desiredExpiryTime: string;
@@ -998,6 +1031,14 @@ interface ResumableUploadOptions {
     resumeSessionUri?: string;
     /** Maximum resume attempts per chunk before giving up. Default: 5 */
     maxResumeAttempts?: number;
+    /**
+     * Optional JSON metadata to include in the initial session-initiation POST.
+     * When present, the initial request uses `Content-Type: application/json; charset=UTF-8`
+     * and the serialized body. Used by APIs like Play Custom App Publishing that
+     * accept resource metadata alongside the media upload (CustomApp.title, etc.).
+     * When omitted, the initial request sends an empty body (default Publisher API behavior).
+     */
+    initialMetadata?: object;
 }
 interface ReleaseSummary {
     releaseName?: string;
@@ -1191,10 +1232,8 @@ interface PlayApiClient {
         getSubscriptionV1(packageName: string, subscriptionId: string, token: string): Promise<SubscriptionPurchase>;
         cancelSubscription(packageName: string, subscriptionId: string, token: string): Promise<void>;
         deferSubscription(packageName: string, subscriptionId: string, token: string, body: SubscriptionDeferRequest): Promise<SubscriptionDeferResponse>;
-        acknowledgeSubscription(packageName: string, subscriptionId: string, token: string, body?: {
-            developerPayload?: string;
-        }): Promise<void>;
-        revokeSubscriptionV2(packageName: string, token: string): Promise<void>;
+        acknowledgeSubscription(packageName: string, subscriptionId: string, token: string, body?: AcknowledgeSubscriptionRequest): Promise<void>;
+        revokeSubscriptionV2(packageName: string, token: string, body?: RevokeSubscriptionV2Request): Promise<void>;
         /** V2 cancel with cancellationType support. (Sep 2025) */
         cancelSubscriptionV2(packageName: string, token: string, body?: SubscriptionsV2CancelRequest): Promise<void>;
         /** V2 defer for subscriptions with add-ons. (Jan 2026) */
@@ -1440,23 +1479,44 @@ interface GamesApiClient {
 }
 declare function createGamesClient(options: ApiClientOptions): GamesApiClient;
 
+/**
+ * A private ("custom") app published via the Google Play Custom App Publishing API.
+ * Once created, these apps are PERMANENTLY private — they cannot be made public.
+ *
+ * Source: `https://playcustomapp.googleapis.com/$discovery/rest?version=v1`
+ */
 interface CustomApp {
-    packageName?: string;
+    /** Output only. Package name Google assigns to the created custom app. */
+    readonly packageName?: string;
+    /** Title for the Android app. Required in practice. */
     title: string;
+    /** Default listing language in BCP 47 format (e.g. "en_US"). */
     languageCode?: string;
+    /** Organizations to which the custom app should be made available. */
     organizations?: Array<{
+        /** ID of the enterprise organization (required when included). */
         organizationId: string;
+        /** Human-readable organization name (optional). */
         organizationName?: string;
     }>;
 }
-interface CustomAppsListResponse {
-    customApps?: CustomApp[];
-    nextPageToken?: string;
-}
+/** Input metadata for `apps.create` — `packageName` is output-only and excluded. */
+type CustomAppCreateMetadata = Omit<CustomApp, "packageName">;
 interface EnterpriseApiClient {
     apps: {
-        create(organizationId: string, app: Partial<CustomApp>): Promise<CustomApp>;
-        list(organizationId: string): Promise<CustomAppsListResponse>;
+        /**
+         * Create and publish a new private custom app. Performs a resumable
+         * upload: the initial POST carries the metadata JSON, subsequent chunks
+         * stream the bundle binary. Returns the created `CustomApp` with the
+         * assigned `packageName`.
+         *
+         * The created app is permanently private and cannot be made public.
+         *
+         * @param accountId - Developer account ID (int64, from Play Console URL)
+         * @param bundlePath - Path to the AAB or APK to upload
+         * @param metadata - CustomApp metadata (title, languageCode, organizations)
+         */
+        create(accountId: string, bundlePath: string, metadata: CustomAppCreateMetadata): Promise<CustomApp>;
     };
 }
 declare function createEnterpriseClient(options: ApiClientOptions): EnterpriseApiClient;
@@ -1470,6 +1530,13 @@ interface HttpClient {
     upload<T>(path: string, filePath: string, contentType: string): Promise<ApiResponse<T>>;
     uploadResumable<T>(path: string, filePath: string, contentType: string, options?: ResumableUploadOptions): Promise<ApiResponse<T>>;
     uploadInternal<T>(path: string, filePath: string, contentType: string): Promise<ApiResponse<T>>;
+    /**
+     * Play Custom App Publishing upload. Sends the media body AND a JSON metadata
+     * object in a single resumable session — the initial session-initiation POST
+     * carries the metadata (CustomApp shape), and subsequent chunks stream the
+     * bundle binary. Used by the Play Custom App API which requires both parts.
+     */
+    uploadCustomApp<T>(path: string, filePath: string, metadata: object, contentType: string): Promise<ApiResponse<T>>;
     download(path: string): Promise<ArrayBuffer>;
 }
 declare function createHttpClient(options: ApiClientOptions): HttpClient;
@@ -1525,4 +1592,4 @@ declare class PlayApiError extends Error {
 /** Files below this threshold use simple upload instead. */
 declare const RESUMABLE_THRESHOLD: number;
 
-export { type Achievement, type Anomaly, type AnomalyDetectionResponse, type ApiClientOptions, type ApiResponse, type ApkInfo, type ApksListResponse, type AppDetails, type AppEdit, type AppRecoveriesListResponse, type AppRecoveryAction, type AppRecoveryTargeting, type BasePlan, type BasePlanMigratePricesRequest, type BatchGetOrdersResponse, type BatchMigratePricesRequest, type BatchMigratePricesResponse, type Bundle, type BundleListResponse, type ChangesInReviewBehavior, type ConvertRegionPricesRequest, type ConvertRegionPricesResponse, type ConvertedRegionPrice, type CountryAvailability, type CreateAppRecoveryActionRequest, type CustomApp, type CustomAppsListResponse, type DataSafety, type DataSafetyDataType, type DataSafetyPurpose, type DeobfuscationFile, type DeobfuscationFileType, type DeobfuscationUploadResponse, type DeveloperComment, type DeveloperPermission, type DeviceGroup, type DeviceSelector, type DeviceTier, type DeviceTierConfig, type DeviceTierConfigsListResponse, type EditCommitOptions, type EnterpriseApiClient, type ErrorIssue, type ErrorIssuesResponse, type ErrorReport, type ErrorReportsResponse, type ExpansionFile, type ExpansionFileType, type ExternalTransaction, type ExternalTransactionAmount, type ExternalTransactionRefund, type ExternallyHostedApk, type ExternallyHostedApkResponse, type GameEvent, type GamesApiClient, type GeneratedApk, type GeneratedApksPerVersion, type Grant, type GrantsListResponse, type HttpClient, type Image, type ImageType, type ImageUploadResponse, type ImagesDeleteAllResponse, type ImagesListResponse, type InAppProduct, type InAppProductListing, type InAppProductsBatchDeleteRequest, type InAppProductsBatchGetRequest, type InAppProductsBatchUpdateRequest, type InAppProductsBatchUpdateResponse, type InAppProductsListResponse, type InternalAppSharingArtifact, type Leaderboard, type LeaderboardScore, type Listing, type ListingsListResponse, type MetricRow, type MetricSetQuery, type MetricSetResponse, type Money, type MutationOptions, type OffersListResponse, type OneTimeOffer, type OneTimeOfferRegionalConfig, type OneTimeOffersListResponse, type OneTimeProduct, type OneTimeProductListing, type OneTimeProductsListResponse, type Order, type OrderLineItem, type PagedResponse, type PaginateOptions, type PlayApiClient, PlayApiError, type ProductPurchase, type ProductPurchaseLineItem, type ProductPurchaseV2, type ProductUpdateLatencyTolerance, RATE_LIMIT_BUCKETS, RESUMABLE_THRESHOLD, type RateLimitBucket, type RateLimiter, type RegionalBasePlanConfig, type Release, type ReleaseNote, type ReleaseStatus, type ReleaseSummary, type ReleasesListResponse, type ReportBucket, type ReportType, type ReportingAggregation, type ReportingApiClient, type ReportingDimension, type ReportsListResponse, type ResumableUploadOptions, type RetryLogEntry, type Review, type ReviewComment, type ReviewReplyRequest, type ReviewReplyResponse, type ReviewsListOptions, type ReviewsListResponse, type StatsDimension, type Subscription, type SubscriptionDeferRequest, type SubscriptionDeferResponse, type SubscriptionListing, type SubscriptionOffer, type SubscriptionOfferPhase, type SubscriptionPurchase, type SubscriptionPurchaseLineItem, type SubscriptionPurchaseV2, type SubscriptionsBatchGetRequest, type SubscriptionsBatchGetResponse, type SubscriptionsBatchUpdateRequest, type SubscriptionsBatchUpdateResponse, type SubscriptionsListResponse, type SubscriptionsV2CancelRequest, type SubscriptionsV2DeferRequest, type SubscriptionsV2DeferResponse, type SystemApkDeviceSpec, type SystemApkOptions, type SystemApkVariant, type TaxAndComplianceSettings, type Testers, type TokenPagination, type Track, type TrackListResponse, type UploadProgressEvent, type UploadResponse, type User, type UserComment, type UsersApiClient, type UsersListResponse, type VitalsMetricSet, type VoidedPurchase, type VoidedPurchasesListResponse, createApiClient, createEnterpriseClient, createGamesClient, createHttpClient, createRateLimiter, createReportingClient, createUsersClient, paginate, paginateAll, paginateParallel, resolveBucket };
+export { type Achievement, type AcknowledgeSubscriptionRequest, type Anomaly, type AnomalyDetectionResponse, type ApiClientOptions, type ApiResponse, type ApkInfo, type ApksListResponse, type AppDetails, type AppEdit, type AppRecoveriesListResponse, type AppRecoveryAction, type AppRecoveryTargeting, type BasePlan, type BasePlanMigratePricesRequest, type BatchGetOrdersResponse, type BatchMigratePricesRequest, type BatchMigratePricesResponse, type Bundle, type BundleListResponse, type ChangesInReviewBehavior, type ConvertRegionPricesRequest, type ConvertRegionPricesResponse, type ConvertedRegionPrice, type CountryAvailability, type CreateAppRecoveryActionRequest, type CustomApp, type CustomAppCreateMetadata, type DataSafety, type DataSafetyDataType, type DataSafetyPurpose, type DeobfuscationFile, type DeobfuscationFileType, type DeobfuscationUploadResponse, type DeveloperComment, type DeveloperPermission, type DeviceGroup, type DeviceSelector, type DeviceTier, type DeviceTierConfig, type DeviceTierConfigsListResponse, type EditCommitOptions, type EnterpriseApiClient, type ErrorIssue, type ErrorIssuesResponse, type ErrorReport, type ErrorReportsResponse, type ExpansionFile, type ExpansionFileType, type ExternalTransaction, type ExternalTransactionAmount, type ExternalTransactionRefund, type ExternallyHostedApk, type ExternallyHostedApkResponse, type GameEvent, type GamesApiClient, type GeneratedApk, type GeneratedApksPerVersion, type Grant, type GrantsListResponse, type HttpClient, type Image, type ImageType, type ImageUploadResponse, type ImagesDeleteAllResponse, type ImagesListResponse, type InAppProduct, type InAppProductListing, type InAppProductsBatchDeleteRequest, type InAppProductsBatchGetRequest, type InAppProductsBatchUpdateRequest, type InAppProductsBatchUpdateResponse, type InAppProductsListResponse, type InternalAppSharingArtifact, type Leaderboard, type LeaderboardScore, type Listing, type ListingsListResponse, type MetricRow, type MetricSetQuery, type MetricSetResponse, type Money, type MutationOptions, type OffersListResponse, type OneTimeOffer, type OneTimeOfferRegionalConfig, type OneTimeOffersListResponse, type OneTimeProduct, type OneTimeProductListing, type OneTimeProductsListResponse, type Order, type OrderLineItem, type PagedResponse, type PaginateOptions, type PlayApiClient, PlayApiError, type ProductPurchase, type ProductPurchaseLineItem, type ProductPurchaseV2, type ProductUpdateLatencyTolerance, RATE_LIMIT_BUCKETS, RESUMABLE_THRESHOLD, type RateLimitBucket, type RateLimiter, type RegionalBasePlanConfig, type Release, type ReleaseNote, type ReleaseStatus, type ReleaseSummary, type ReleasesListResponse, type ReportBucket, type ReportType, type ReportingAggregation, type ReportingApiClient, type ReportingDimension, type ReportsListResponse, type ResumableUploadOptions, type RetryLogEntry, type Review, type ReviewComment, type ReviewReplyRequest, type ReviewReplyResponse, type ReviewsListOptions, type ReviewsListResponse, type RevokeSubscriptionV2Request, type StatsDimension, type Subscription, type SubscriptionDeferRequest, type SubscriptionDeferResponse, type SubscriptionListing, type SubscriptionOffer, type SubscriptionOfferPhase, type SubscriptionPurchase, type SubscriptionPurchaseLineItem, type SubscriptionPurchaseV2, type SubscriptionsBatchGetRequest, type SubscriptionsBatchGetResponse, type SubscriptionsBatchUpdateRequest, type SubscriptionsBatchUpdateResponse, type SubscriptionsListResponse, type SubscriptionsV2CancelRequest, type SubscriptionsV2DeferRequest, type SubscriptionsV2DeferResponse, type SystemApkDeviceSpec, type SystemApkOptions, type SystemApkVariant, type TaxAndComplianceSettings, type Testers, type TokenPagination, type Track, type TrackListResponse, type UploadProgressEvent, type UploadResponse, type User, type UserComment, type UsersApiClient, type UsersListResponse, type VitalsMetricSet, type VoidedPurchase, type VoidedPurchasesListResponse, createApiClient, createEnterpriseClient, createGamesClient, createHttpClient, createRateLimiter, createReportingClient, createUsersClient, paginate, paginateAll, paginateParallel, resolveBucket };

package/dist/index.js

@@ -64,7 +64,13 @@ async function resumableUpload(uploadUrl, filePath, contentType, ctx, options) {
   const totalBytes = fileStats.size;
   let sessionUri = options?.resumeSessionUri;
   if (!sessionUri) {
-    sessionUri = await initiateSession(uploadUrl, contentType, totalBytes, ctx);
+    sessionUri = await initiateSession(
+      uploadUrl,
+      contentType,
+      totalBytes,
+      ctx,
+      options?.initialMetadata
+    );
   }
   const startTime = Date.now();
   let offset = 0;
@@ -170,21 +176,29 @@ async function resumableUpload(uploadUrl, filePath, contentType, ctx, options) {
     await fh?.close();
   }
 }
-async function initiateSession(uploadUrl, contentType, totalBytes, ctx) {
+async function initiateSession(uploadUrl, contentType, totalBytes, ctx, initialMetadata) {
   const token = await ctx.getAccessToken();
   const url = uploadUrl.includes("?") ? `${uploadUrl}&uploadType=resumable` : `${uploadUrl}?uploadType=resumable`;
+  const hasMetadata = initialMetadata !== void 0;
+  const metadataBody = hasMetadata ? JSON.stringify(initialMetadata) : "";
+  const metadataBodyBytes = hasMetadata ? Buffer.byteLength(metadataBody, "utf8") : 0;
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    "X-Upload-Content-Type": contentType,
+    "X-Upload-Content-Length": String(totalBytes),
+    "Content-Length": String(metadataBodyBytes)
+  };
+  if (hasMetadata) {
+    headers["Content-Type"] = "application/json; charset=UTF-8";
+  }
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 6e4);
   let response;
   try {
     response = await fetch(url, {
       method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "X-Upload-Content-Type": contentType,
-        "X-Upload-Content-Length": String(totalBytes),
-        "Content-Length": "0"
-      },
+      headers,
+      body: hasMetadata ? metadataBody : void 0,
       signal: controller.signal
     });
   } finally {
@@ -405,6 +419,7 @@ function validateFilePath(filePath) {
 var BASE_URL = "https://androidpublisher.googleapis.com/androidpublisher/v3/applications";
 var UPLOAD_BASE_URL = "https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications";
 var INTERNAL_SHARING_UPLOAD_BASE_URL = "https://androidpublisher.googleapis.com/upload/internalappsharing/v3/applications";
+var CUSTOM_APP_UPLOAD_BASE_URL = "https://playcustomapp.googleapis.com/upload/playcustomapp/v1/accounts";
 function envInt2(name) {
   const val = process.env[name];
   if (val === void 0) return void 0;
@@ -938,6 +953,23 @@ function createHttpClient(options) {
     uploadInternal(path, filePath, contentType) {
       return uploadRequest(path, filePath, contentType, INTERNAL_SHARING_UPLOAD_BASE_URL);
     },
+    async uploadCustomApp(path, filePath, metadata, contentType) {
+      const safeFilePath = validateFilePath(filePath);
+      const uploadUrl = `${CUSTOM_APP_UPLOAD_BASE_URL}${path}`;
+      return resumableUpload(
+        uploadUrl,
+        safeFilePath,
+        contentType,
+        {
+          getAccessToken: () => options.auth.getAccessToken(),
+          maxRetries,
+          baseDelay,
+          maxDelay,
+          onRetry
+        },
+        { initialMetadata: metadata }
+      );
+    },
     async download(path) {
       const url = `${options.baseUrl ?? BASE_URL}${path}`;
       const token = await options.auth.getAccessToken();
@@ -1662,8 +1694,11 @@ function createApiClient(options) {
           body ?? {}
         );
       },
-      async revokeSubscriptionV2(packageName, token) {
-        await http.post(`/${packageName}/purchases/subscriptionsv2/tokens/${token}:revoke`);
+      async revokeSubscriptionV2(packageName, token, body) {
+        await http.post(
+          `/${packageName}/purchases/subscriptionsv2/tokens/${token}:revoke`,
+          body ?? {}
+        );
       },
       async cancelSubscriptionV2(packageName, token, body) {
         await http.post(`/${packageName}/purchases/subscriptionsv2/tokens/${token}:cancel`, body);
@@ -2218,17 +2253,58 @@ function createGamesClient(options) {
 }
 
 // src/enterprise-client.ts
-var ENTERPRISE_BASE_URL = "https://playcustomapp.googleapis.com/playcustomapp/v1/organizations";
+import { stat as stat3 } from "fs/promises";
+function assertAccountId(accountId) {
+  if (!/^\d+$/.test(accountId)) {
+    throw new PlayApiError(
+      `Developer account ID must be numeric (got "${accountId}").`,
+      "ENTERPRISE_INVALID_ACCOUNT_ID",
+      void 0,
+      [
+        "Find your developer account ID in the Play Console URL:",
+        "  https://play.google.com/console/developers/[ID]",
+        "The ID is a long integer, not your Workspace or Cloud Identity organization ID."
+      ].join("\n")
+    );
+  }
+}
+async function assertBundleExists(bundlePath) {
+  try {
+    await stat3(bundlePath);
+  } catch {
+    throw new PlayApiError(
+      `Bundle file not found: ${bundlePath}`,
+      "ENTERPRISE_BUNDLE_NOT_FOUND",
+      void 0,
+      "Verify the path to your AAB or APK is correct."
+    );
+  }
+}
+function detectContentType(bundlePath) {
+  const lower = bundlePath.toLowerCase();
+  if (lower.endsWith(".aab")) {
+    return "application/octet-stream";
+  }
+  if (lower.endsWith(".apk")) {
+    return "application/vnd.android.package-archive";
+  }
+  return "application/octet-stream";
+}
 function createEnterpriseClient(options) {
-  const http = createHttpClient({ ...options, baseUrl: ENTERPRISE_BASE_URL });
+  const http = createHttpClient(options);
   return {
     apps: {
-      async create(organizationId, app) {
-        const { data } = await http.post(`/${organizationId}/apps`, app);
-        return data;
-      },
-      async list(organizationId) {
-        const { data } = await http.get(`/${organizationId}/apps`);
+      async create(accountId, bundlePath, metadata) {
+        assertAccountId(accountId);
+        await assertBundleExists(bundlePath);
+        const contentType = detectContentType(bundlePath);
+        const path = `/${accountId}/customApps`;
+        const { data } = await http.uploadCustomApp(
+          path,
+          bundlePath,
+          metadata,
+          contentType
+        );
         return data;
       }
     }