@mpgd/game-services 0.33.1 → 0.34.0

package/dist/google-play-rtdn.d.ts

@@ -0,0 +1,248 @@
+import { type GooglePlayVoidedPurchasesClient } from './google-play-store-server.js';
+import type { GameServicesStore } from './server.js';
+/**
+* Google Play Real-time developer notifications (RTDN) delivered by a Cloud
+* Pub/Sub push subscription: the fast path for revoking a refunded or voided
+* one-time purchase. The Voided Purchases API sweep
+* (`sweepGooglePlayVoidedPurchases`) stays required next to it, because a
+* push can be lost (a misconfigured subscription, a message that outlives
+* its retention); both revoke through `revokeGooglePlayVoidedPurchase`, keyed
+* by the purchase token, so whichever comes second is a no-op.
+*
+* - RTDN reference: https://developer.android.com/google/play/billing/rtdn-reference
+* - Push authentication: https://cloud.google.com/pubsub/docs/authenticate-push-subscriptions
+* - Push acknowledgement (102, 200, 201, 202, 204 ack; anything else is
+*   redelivered): https://cloud.google.com/pubsub/docs/push
+* - Payload unwrapping: https://cloud.google.com/pubsub/docs/payload-unwrapping
+* - Voided Purchases API (6,000 queries a day, 30 in any 30 seconds):
+*   https://developers.google.com/android-publisher/voided-purchases
+*/
+/** Issuers of Google-signed ID tokens (Google's OpenID Connect guide). */
+export declare const googleIdTokenIssuers: readonly string[];
+/**
+* Google's published ID token signing keys (the `jwks_uri` of
+* https://accounts.google.com/.well-known/openid-configuration).
+*/
+export declare const googleIdTokenJwksUrl = "https://www.googleapis.com/oauth2/v3/certs";
+/** Google's keys could not be read: answer non-2xx so Pub/Sub redelivers. */
+export declare class GoogleIdTokenKeysUnavailableError extends Error {
+  readonly name = "GoogleIdTokenKeysUnavailableError";
+}
+/** The source of Google's RS256 ID token signing keys; inject a fake in tests. */
+export interface GoogleIdTokenSigningKeys {
+  /**
+  * The published public key with this key id, or undefined when Google does
+  * not publish one. Throws `GoogleIdTokenKeysUnavailableError` when the keys
+  * cannot be read.
+  */
+  getSigningKey(input: {
+    readonly kid: string;
+    readonly signal: AbortSignal;
+  }): Promise<JsonWebKey | undefined>;
+}
+export interface GoogleIdTokenSigningKeysOptions {
+  readonly fetch?: typeof fetch;
+  readonly jwksUrl?: string;
+  /** Milliseconds since the epoch; for the cache. */
+  readonly now?: () => number;
+}
+/**
+* How long past its cache expiry a held key still verifies while Google's
+* key endpoint cannot be read (an outage, or the refresh throttle). Six
+* hours rides out a long endpoint outage without dropping pushes, and is the
+* longest a push is retried (`maxUnmatchedVoidRetryMs`); past it a key Google
+* may have withdrawn is no longer trusted and pushes answer 503 until the
+* keys can be read again.
+*/
+export declare const googleIdTokenKeyStaleGraceMs: number;
+/**
+* Reads Google's ID token keys from `googleIdTokenJwksUrl`, cached for the
+* response's `Cache-Control: max-age` (one minute to a day; an hour without
+* one) and refreshed early for a key id it does not hold: Google rotates its
+* keys. Fetches, failed ones included, are at least a minute apart. While
+* the keys cannot be read (an outage, or between throttled fetches), a held
+* key answers for `googleIdTokenKeyStaleGraceMs` past its cache expiry; past
+* that, an outage is `GoogleIdTokenKeysUnavailableError` and a throttled
+* lookup finds no key. One instance per isolate shares the cache.
+*/
+export declare function createGoogleIdTokenSigningKeys(options?: GoogleIdTokenSigningKeysOptions): GoogleIdTokenSigningKeys;
+export interface GooglePubSubPushAuthentication {
+  /** The audience set on the push subscription (`--push-auth-token-audience`). */
+  readonly audience: string;
+  /** The service account the push subscription signs as (`--push-auth-service-account`). */
+  readonly serviceAccountEmail: string;
+  readonly keys: GoogleIdTokenSigningKeys;
+  /** Clock skew allowed on `exp` and `iat`, in seconds; 60 by default. */
+  readonly clockSkewSeconds?: number;
+}
+export type GooglePubSubPushTokenVerification = {
+  readonly status: 'verified';
+} | {
+  readonly status: 'rejected';
+  readonly reason: string;
+};
+/**
+* Verifies the OIDC token a Pub/Sub push subscription with authentication
+* sends as `Authorization: Bearer <JWT>`: an RS256 signature by one of
+* Google's published keys, a Google issuer, the subscription's audience, its
+* service account (`email`, `email_verified`), and `exp`/`iat`. Throws
+* `GoogleIdTokenKeysUnavailableError` when Google's keys cannot be read.
+*/
+export declare function verifyGooglePubSubPushToken(input: GooglePubSubPushAuthentication & {
+  readonly authorization: string | null | undefined;
+  readonly signal: AbortSignal;
+  /** Milliseconds since the epoch. */
+  readonly now?: () => number;
+}): Promise<GooglePubSubPushTokenVerification>;
+/** `voidedPurchaseNotification.productType` (RTDN reference). */
+export declare const googlePlayRtdnProductType: Readonly<{
+  readonly subscription: 1;
+  readonly oneTime: 2;
+}>;
+/** `voidedPurchaseNotification.refundType` (RTDN reference). */
+export declare const googlePlayRtdnRefundType: Readonly<{
+  readonly fullRefund: 1;
+  readonly quantityBasedPartialRefund: 2;
+}>;
+/** The decoded `message.data`: one notification kind besides `version`, `packageName`, `eventTimeMillis`. */
+export interface GooglePlayDeveloperNotification {
+  readonly version?: string;
+  readonly packageName: string;
+  /** Milliseconds since the epoch (an int64 string or a number in the JSON). */
+  readonly eventTimeMillis?: number;
+  readonly voidedPurchaseNotification?: {
+    readonly purchaseToken?: unknown;
+    readonly orderId?: unknown;
+    readonly productType?: unknown;
+    readonly refundType?: unknown;
+  };
+  readonly oneTimeProductNotification?: Readonly<Record<string, unknown>>;
+  readonly subscriptionNotification?: Readonly<Record<string, unknown>>;
+  readonly testNotification?: Readonly<Record<string, unknown>>;
+  readonly [kind: string]: unknown;
+}
+export type GooglePlayDeveloperNotificationPush = {
+  readonly status: 'decoded';
+  readonly messageId?: string;
+  readonly notification: GooglePlayDeveloperNotification;
+} | {
+  readonly status: 'rejected';
+  readonly reason: string;
+  readonly messageId?: string;
+};
+/**
+* Decodes a Pub/Sub push body into the `DeveloperNotification` it carries.
+* Both push formats are accepted: the default wrapped body (`{ message:
+* { data, messageId }, subscription }`, the notification base64 in `data`)
+* and an unwrapped one (payload unwrapping on: the body is the notification
+* JSON itself, with a top-level `packageName` and no `message`). An
+* unwrapped push carries its message id only in the
+* `x-goog-pubsub-message-id` header when "write metadata" is on; pass it as
+* `messageId`.
+*/
+export declare function decodeGooglePlayDeveloperNotificationPush(body: unknown, options?: {
+  readonly messageId?: string | null;
+}): GooglePlayDeveloperNotificationPush;
+export interface HandleGooglePlayDeveloperNotificationInput {
+  readonly store: GameServicesStore;
+  /** The app's package; a notification for another package is acknowledged and ignored. */
+  readonly packageName: string;
+  /**
+  * The Voided Purchases API (the sweep's client). A voided notification is
+  * only a trigger: the void is revoked once this lists it, with the listed
+  * entry, so the ledger records what the sweep would.
+  */
+  readonly voidedPurchases: GooglePlayVoidedPurchasesClient;
+  /** The push request body parsed from JSON. Authenticate the push before calling this. */
+  readonly body: unknown;
+  /** An unwrapped push's `x-goog-pubsub-message-id` header, for logs. */
+  readonly messageId?: string | null;
+  /** Bounds the Voided Purchases API lookup. */
+  readonly signal: AbortSignal;
+  readonly now?: () => string;
+  /**
+  * How long after the notification's `eventTimeMillis` a void that the
+  * Voided Purchases API does not list yet, or whose grant this ledger does
+  * not hold, is answered `retry` instead of `ignored`; 1 hour by default, at
+  * most `maxUnmatchedVoidRetryMs` (6 hours), `0` acknowledges at once. It
+  * covers Google's lag in listing the void and a purchase whose grant is
+  * still being written; past it the message is acknowledged and the sweep
+  * reads the void again.
+  */
+  readonly unmatchedVoidRetryMs?: number;
+}
+/** Default of `unmatchedVoidRetryMs`. */
+export declare const defaultUnmatchedVoidRetryMs: number;
+/** Upper bound of `unmatchedVoidRetryMs`. */
+export declare const maxUnmatchedVoidRetryMs: number;
+/**
+* The lookup window around the notification's event time: this much before
+* it (Google's own clocks), and up to `maxUnmatchedVoidRetryMs` after it
+* (Google lists a void a little after it records it), never past now.
+*/
+export declare const googlePlayRtdnLookupLeadMs: number;
+/** Voided Purchases API pages one notification reads at most (a page holds up to 1,000 voids). */
+export declare const googlePlayRtdnLookupMaxPages = 2;
+/**
+* Every outcome's `orderId` is the order id of the matched Voided Purchases
+* API entry, never the push body's: it is absent until Google lists the void.
+*/
+export type GooglePlayDeveloperNotificationOutcome = 
+/** The grant was reversed (or already had been: a redelivery, or the sweep came first). */
+{
+  readonly status: 'revoked';
+  readonly messageId?: string;
+  readonly ledgerEntryId: string;
+  readonly alreadyProcessed: boolean;
+  readonly orderId?: string;
+}
+/** Nothing to do (a test, a subscription, a partial refund, another package): acknowledge. */
+| {
+  readonly status: 'ignored';
+  readonly reason: string;
+  readonly messageId?: string;
+  readonly orderId?: string;
+}
+/** The ledger refused the revocation; a redelivery cannot fix it, so acknowledge and alert. */
+| {
+  readonly status: 'conflict';
+  readonly reason: string;
+  readonly messageId?: string;
+  readonly orderId?: string;
+}
+/** Malformed: acknowledged so Pub/Sub does not redeliver it until retention runs out. */
+| {
+  readonly status: 'rejected';
+  readonly reason: string;
+  readonly messageId?: string;
+}
+/**
+* Answer non-2xx so Pub/Sub redelivers: the Voided Purchases API failed or
+* does not list the void yet, or this ledger may still be writing its grant.
+*/
+| {
+  readonly status: 'retry';
+  readonly reason: string;
+  readonly messageId?: string;
+  readonly orderId?: string;
+};
+/**
+* Applies one RTDN push to the ledger. A `voidedPurchaseNotification` of a
+* one-time product with a full refund is confirmed with the Voided Purchases
+* API (one window around the event time, matched on the purchase token) and
+* the listed entry is revoked through `revokeGooglePlayVoidedPurchase`: the
+* sweep's path, idempotency key, reason, source, and void time. A push alone
+* never revokes, so a message published to the topic by anyone but Google
+* cannot reverse a grant Google did not void. A void not listed yet, or
+* whose grant this ledger does not hold, is `retry` while recent
+* (`unmatchedVoidRetryMs`), `ignored` after; a lookup failure is `retry`. A
+* quantity-based partial refund is ignored without a lookup, as the sweep
+* (which lists full refunds only) ignores it. Test, subscription, one-time
+* product purchase, and every other kind are `ignored`: the kit sells no
+* Play subscriptions, and a purchase is granted only when the game verifies
+* it. A thrown error (a store outage) is not an outcome: answer 5xx so
+* Pub/Sub redelivers.
+*/
+export declare function handleGooglePlayDeveloperNotification(input: HandleGooglePlayDeveloperNotificationInput): Promise<GooglePlayDeveloperNotificationOutcome>;
+/** The HTTP status to answer Pub/Sub with: 200 acknowledges, 503 asks for a redelivery. */
+export declare function googlePlayDeveloperNotificationHttpStatus(outcome: GooglePlayDeveloperNotificationOutcome): 200 | 503;