glitch-javascript-sdk 3.10.8 → 3.15.0

package/dist/esm/routes/FestivalNetworkingRoute.d.ts

@@ -0,0 +1,7 @@
+import Route from './interface';
+/** Participant-only festival networking; all access checks are enforced by the API. */
+export default class FestivalNetworkingRoute {
+    static routes: {
+        [key: string]: Route;
+    };
+}

package/dist/esm/routes/MicrotransactionsRoute.d.ts

@@ -0,0 +1,8 @@
+import Route from './interface';
+/** Consumer-facing commerce routes. Signed provider webhooks are deliberately not client APIs. */
+declare class MicrotransactionsRoute {
+    static routes: {
+        [key: string]: Route;
+    };
+}
+export default MicrotransactionsRoute;

package/dist/esm/util/MicrotransactionBridge.d.ts

@@ -0,0 +1,93 @@
+import type { MicrotransactionHandoffClaim } from '../api/Microtransactions';
+/** A one-time notification, never a receipt or authorization to grant goods. */
+export interface MicrotransactionPurchaseMessage {
+    type: 'glitch.microtransaction.updated';
+    version: 1;
+    title_id: string;
+    checkout_session_id: string;
+    order_id: string;
+    /** Cryptographically random value bound to the checkout session at creation. */
+    nonce: string;
+    /** Server-issued one-time code; not an account or player bearer token. */
+    claim_code: string;
+}
+/** Exact authoritative /handoffs/claim response, not the hosted session DTO. */
+export type MicrotransactionVerifiedSession = MicrotransactionHandoffClaim;
+export interface MicrotransactionBridgeOptions<T extends MicrotransactionVerifiedSession> {
+    titleId: string;
+    checkoutSessionId: string;
+    /** Exact trusted Glitch checkout origin, with no path, wildcard, or credentials. */
+    checkoutOrigin: string;
+    /** The actual Window returned by window.open or the checkout iframe.contentWindow. */
+    checkoutWindow: Window;
+    /** At least 128 bits of randomness; use createMicrotransactionNonce(). */
+    nonce: string;
+    /**
+     * Exchange message.claim_code at Glitch using claimHandoff(titleId,
+     * {claim_code, nonce, return_origin: window.location.origin,
+     * checkout_session_id}). Return response.data.data, the actual claim DTO.
+     * The message has already passed source/origin/nonce checks but is still NOT
+     * proof of payment. The server validates and consumes the one-time code.
+     * Never exchange a site-wide login token with the game or put credentials in
+     * postMessage, analytics, logs, or query strings.
+     */
+    verify: (message: MicrotransactionPurchaseMessage) => Promise<T>;
+    /**
+     * Restore using the previously verified scoped token plus getOrder and
+     * listEntitlements. Return the claim identity/token with current inventory.
+     * Never redeem the code again. When its token expires, return the player to
+     * the authenticated hosted flow to obtain a fresh scoped handoff.
+     */
+    refresh?: (previous: T) => Promise<T>;
+    /** Refresh display/inventory from the verified result. Make local effects idempotent. */
+    onVerified: (result: T) => void | Promise<void>;
+    /** A failed refresh is not a failed payment. Keep the same session and retry. */
+    onError?: (error: unknown) => void;
+    /** Explicit local development only; production checkout must use HTTPS. */
+    allowLocalDevelopment?: boolean;
+    /** Defaults to window. Useful for browser integration tests. */
+    eventTarget?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+}
+/** Restore authenticates an existing receipt in Glitch and creates a new session. */
+export interface MicrotransactionRestoreBridgeOptions<T extends MicrotransactionVerifiedSession> extends Omit<MicrotransactionBridgeOptions<T>, 'checkoutSessionId'> {
+    /** Previously verified receipt/order ID. This, not the old expired session ID, is pinned. */
+    orderId: string;
+}
+export interface MicrotransactionBridge {
+    /**
+     * Refresh only after a successful claim, using options.refresh and its scoped
+     * token. Concurrent refreshes share one request. A lost first-claim response
+     * requires a fresh handoff from the authenticated hosted page, not code replay
+     * or a new payment. No automatic polling or token refresh is performed.
+     */
+    refresh(): Promise<void>;
+    /** Remove the listener. In-flight results cannot call onVerified after disposal. */
+    dispose(): void;
+}
+/** Generate a 256-bit browser nonce. Fails closed without secure Web Crypto. */
+export declare function createMicrotransactionNonce(): string;
+/**
+ * Listen for Glitch-hosted, game-branded checkout changes with strict origin,
+ * source, title, session, and nonce binding. Message data cannot grant an item.
+ * The caller always verifies the session at Glitch before updating inventory.
+ *
+ * Prefer openMicrotransactionOverlay with the exact server-returned URL. The
+ * game stays mounted; no top-level navigation fallback is permitted. If an
+ * embedded flow is unavailable, show retry/close and preserve the game state.
+ * refresh() requires an already verified claim. Keep
+ * secrets in memory/session storage or a URL fragment, never query parameters.
+ * Dispose on game unmount/account change. Reconnect restores ownership through
+ * the authenticated entitlement API, not a saved "purchase successful" flag.
+ */
+export declare function createMicrotransactionBridge<T extends MicrotransactionVerifiedSession>(options: MicrotransactionBridgeOptions<T>): MicrotransactionBridge;
+/**
+ * Restore-only bridge for /games/:titleId/purchases/restore. Pin the prior order,
+ * fresh nonce, exact Glitch origin and opened window. The hosted signed-in page
+ * creates a NEW session; the server-verified claim must match that new session
+ * and the pinned order. This does not relax purchase-session binding.
+ *
+ * Open the hosted restore page, never request the account JWT in the game.
+ * verify(message) exchanges the code using message.checkout_session_id. All
+ * duplicate-code, expiry and same-player refresh safeguards still apply.
+ */
+export declare function createMicrotransactionRestoreBridge<T extends MicrotransactionVerifiedSession>(options: MicrotransactionRestoreBridgeOptions<T>): MicrotransactionBridge;

package/dist/esm/util/MicrotransactionOverlay.d.ts

@@ -0,0 +1,59 @@
+import { MicrotransactionCreatedCheckoutSession, MicrotransactionHandoffClaim, MicrotransactionOrder } from '../api/Microtransactions';
+export interface MicrotransactionOverlayOptions {
+    titleId: string;
+    /** Exact configured Glitch HTTPS origin, never taken from postMessage data. */
+    checkoutOrigin: string;
+    /** Result of createCheckoutSession or createRestoreSession; keep its capability private. */
+    session: MicrotransactionCreatedCheckoutSession;
+    /** Replace displayed inventory from verified backend data; never increment blindly. */
+    onVerified: (claim: MicrotransactionHandoffClaim) => void | Promise<void>;
+    /** Pause game input/audio here. The SDK never unmounts or resets the game. */
+    onOpen?: () => void;
+    /** Resume game input/audio here. Called once, even on escape/error cleanup. */
+    onClose?: (reason: 'dismissed' | 'completed' | 'unavailable') => void;
+    /** Receipt/status-only update after close; this callback does not authorize item grants. */
+    onOrderUpdate?: (order: MicrotransactionOrder | null) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+    label?: string;
+    /** Permit HTTP loopback/.test origins only for explicit local development. */
+    allowLocalDevelopment?: boolean;
+    /** Defaults to the caller's document, including when the game itself is embedded. */
+    document?: Document;
+    /** Bounded network timeout; defaults to 15 seconds. */
+    timeoutMs?: number;
+    /** Per-phase iframe load/application-ready timeout; 1–60 seconds, defaults to 20 seconds. */
+    frameLoadTimeoutMs?: number;
+}
+/** Hosted page signals usable checkout/account UI, never payment or inventory authority. */
+export interface MicrotransactionReadyMessage {
+    type: 'glitch.microtransaction.ready';
+    version: 1;
+    title_id: string;
+    checkout_session_id: string;
+    nonce: string;
+}
+export interface MicrotransactionOverlay {
+    readonly element: HTMLDialogElement;
+    readonly iframe: HTMLIFrameElement;
+    /** Refresh verified inventory, or limited receipt status before the first claim. */
+    refresh(): Promise<void>;
+    /** Removes only this modal, restores focus/input, and refreshes authoritative state. */
+    close(reason?: 'dismissed' | 'completed' | 'unavailable'): Promise<void>;
+    /** Reload only the same checkout iframe/session. Never starts another payment. */
+    retry(): void;
+}
+/**
+ * Mount Glitch checkout IN the running game. The game document, URL and session
+ * stay intact. Uses a modal dialog with focus restore and a sandboxed payment
+ * iframe. No top-navigation permission or top-level/popup-blocked fallback exists.
+ * Only bank/OAuth verification may open a controlled provider window from inside
+ * the frame. If embedding is unavailable, show retry/close instead of navigating.
+ *
+ * Receipt messages must originate from this exact iframe.contentWindow and pass
+ * origin/title/session/nonce checks. The SDK redeems the one-time claim at Glitch
+ * and uses the returned scoped player token only on commerce requests. Closing
+ * does not cancel an uncertain payment, grant goods, or discard the game state.
+ */
+export declare function openMicrotransactionOverlay(options: MicrotransactionOverlayOptions): MicrotransactionOverlay;
+/** Same in-game modal for anonymous-safe restore sessions; never opens a new payment. */
+export declare function openMicrotransactionRestoreOverlay(options: MicrotransactionOverlayOptions): MicrotransactionOverlay;

package/dist/esm/util/Requests.d.ts

@@ -1,4 +1,4 @@
-import { AxiosPromise, AxiosProgressEvent } from 'axios';
+import { AxiosPromise, AxiosRequestConfig, AxiosProgressEvent } from 'axios';
 import Config from '../config/Config';
 import Route from '../routes/interface';
 import Response from './Response';
@@ -25,12 +25,14 @@ declare class Requests {
     static put<T>(url: string, data: any, params?: Record<string, any>): AxiosPromise<Response<T>>;
     static patch<T>(url: string, data: any, params?: Record<string, any>): AxiosPromise<Response<T>>;
     static delete<T>(url: string, params?: Record<string, any>): AxiosPromise<Response<T>>;
-    static uploadFile<T>(url: string, filename: string, file: File | Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void): AxiosPromise<Response<T>>;
+    static uploadFile<T>(url: string, filename: string, file: File | Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout'>): AxiosPromise<Response<T>>;
     static postFormData<T>(url: string, formData: FormData, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void): AxiosPromise<Response<T>>;
     static uploadBlob<T>(url: string, filename: string, blob: Blob, data?: any, params?: Record<string, any>, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void): AxiosPromise<Response<T>>;
     static uploadFileInChunks<T>(file: File, uploadUrl: string, onProgress?: (totalSize: number, amountUploaded: number) => void, data?: any, chunkSize?: number): Promise<void>;
     static processRoute<T>(route: Route, data?: object, routeReplace?: {
         [key: string]: any;
-    }, params?: Record<string, any>): AxiosPromise<Response<T>>;
+    }, params?: Record<string, any>, options?: Pick<AxiosRequestConfig, 'signal' | 'timeout' | 'headers'> & {
+        excludeCommunityContext?: boolean;
+    }): AxiosPromise<Response<T>>;
 }
 export default Requests;