glitch-javascript-sdk 3.5.3 → 3.7.0

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

@@ -0,0 +1,11 @@
+import Route from './interface';
+declare class GameAdvertisingRoute {
+    /**
+     * Route templates for publisher game-ad inventory, telemetry, earnings, and
+     * site administration. Placeholders are expanded by Requests.processRoute.
+     */
+    static routes: {
+        [key: string]: Route;
+    };
+}
+export default GameAdvertisingRoute;

package/dist/index.d.ts

@@ -1893,6 +1893,50 @@ declare class Communities {
     static saveInfluencerToPool<T>(community_id: string, data: object): AxiosPromise<Response<T>>;
 }
 
+/** Human-readable earning categories returned by influencer payout APIs. */
+type InfluencerPayoutSourceType = "campaign_compensation" | "ad_revenue_share" | "subscription_residual" | "manual_adjustment";
+/** Auditable metrics and creator-content attribution attached to a payout. */
+interface InfluencerPayoutBreakdown {
+    label?: string;
+    payment_method?: "flat" | "performance" | "hybrid";
+    provider?: string;
+    period_start?: string;
+    period_end?: string;
+    impressions?: number;
+    clicks?: number;
+    short_link_id?: string | null;
+    short_link_click_id?: string | null;
+    social_media_post_id?: string | null;
+    tracking_link_label?: string | null;
+    social_platform?: string | null;
+    social_post_url?: string | null;
+}
+/** One campaign or advertising earning payable to the authenticated influencer. */
+interface InfluencerPayout {
+    id: string;
+    user_id: string;
+    campaign_id: string;
+    amount: number;
+    currency: string;
+    status: "pending" | "completed" | "failed";
+    payout_date?: string | null;
+    source_type: InfluencerPayoutSourceType;
+    source_label: string;
+    source_reference_id?: string | null;
+    breakdown?: InfluencerPayoutBreakdown;
+    campaign?: Record<string, any>;
+}
+/** Optional filters for the authenticated influencer's payout history. */
+interface InfluencerPayoutQuery {
+    campaign_id?: string;
+    month?: number;
+    year?: number;
+    amount?: number;
+    status?: "pending" | "completed" | "failed";
+    source_type?: InfluencerPayoutSourceType;
+    orderBy?: "created_at" | "amount";
+    orderDirection?: "asc" | "desc";
+}
 declare class Users {
     /**
      * List all the users.
@@ -1935,16 +1979,17 @@ declare class Users {
      */
     static getCampaignInvites<T>(params?: Record<string, any>): AxiosPromise<Response<T>>;
     /**
-     * Gets payouts from past campaings
+     * Gets the authenticated influencer's payouts from campaigns and attributed
+     * game advertising. Advertising revenue is returned as a separate additive
+     * source with provider-period metrics and tracking-link/social-post IDs.
      *
      * @see https://api.glitch.fun/api/documentation#/Users%20Route/showMe
      *
-     * @param user_id The id of the user to update.
-     * @param data The data to update.
+     * @param params Optional campaign, date, status, source, and ordering filters.
      *
      * @returns promise
      */
-    static getPayouts<T>(params?: Record<string, any>): AxiosPromise<Response<T>>;
+    static getPayouts<T = InfluencerPayout[]>(params?: InfluencerPayoutQuery): AxiosPromise<Response<T>>;
     /**
      * Sync the current influencer's information.
      *
@@ -11027,6 +11072,92 @@ declare class MarketResearch {
     static exportGame(game_id: string, params?: Record<string, any>): AxiosPromise<Blob>;
 }
 
+interface GameAdEventPayload {
+    /** Opaque token returned by the server-created advertising manifest. */
+    token: string;
+    /** Client idempotency UUID. Reuse is valid only within the same ad session. */
+    event_uuid?: string;
+    /** Provider that produced or attempted the event. */
+    provider: string;
+    /** Stable Glitch placement name, such as game_banner or game_video. */
+    placement: string;
+    /** Normalized creative/ad format. */
+    format: 'banner' | 'video' | 'interstitial' | 'rewarded' | 'in_game_image' | 'in_game_video' | 'other';
+    /** Normalized SDK/ad lifecycle event. */
+    event_type: 'sdk_ready' | 'request_started' | 'loaded' | 'channel_registered' | 'measurement' | 'no_fill' | 'fallback_shown' | 'started' | 'impression' | 'viewable' | 'clicked' | 'completed' | 'skipped' | 'closed' | 'paused_game' | 'resumed_game' | 'error';
+    /** Optional provider-native event or impression identifier. */
+    provider_event_id?: string;
+    /** Non-sensitive provider diagnostics and event context. */
+    metadata?: Record<string, any>;
+    /** ISO 8601 client-observed timestamp. Defaults to server receipt time. */
+    occurred_at?: string;
+}
+/** Provider-neutral intrinsic-ad surface declared by a game developer. */
+interface GameInGameAdPlacement {
+    id?: string;
+    title_id?: string;
+    provider?: 'anzu';
+    placement_key: string;
+    channel_name: string;
+    surface_type: 'mesh' | 'sprite' | 'ui_image' | 'raw_image' | 'html' | 'electron_shell';
+    scene_name?: string | null;
+    aspect_ratio: number;
+    allow_images: boolean;
+    allow_videos: boolean;
+    allow_audio?: boolean;
+    is_dynamic: boolean;
+    is_clickable: boolean;
+    shrink_to_fit: boolean;
+    fallback_media_url?: string | null;
+    status: 'active' | 'disabled';
+    metadata?: Record<string, any> | null;
+}
+/** Public delivery identity for a provider and runtime platform. */
+interface GameAdProviderApp {
+    id?: string;
+    title_id?: string | null;
+    provider: 'anzu';
+    platform: 'web' | 'electron_macos' | 'electron_windows' | 'electron_linux' | 'unity_webgl' | 'cocos_web' | 'construct_web';
+    app_key: string;
+    bundle_id?: string | null;
+    mode: 'integration' | 'production';
+    integration_type: 'managed' | 'direct';
+    status: 'active' | 'disabled' | 'pending';
+    metadata?: Record<string, any> | null;
+}
+/**
+ * Typed client for platform-served game advertising.
+ *
+ * These endpoints manage publisher inventory displayed around playable games;
+ * they are intentionally separate from APIs used to buy advertising campaigns.
+ */
+declare class GameAdvertising {
+    /** Return developer-visible ad-earnings settings for a title. */
+    static settings<T>(title_id: string): AxiosPromise<Response<T>>;
+    /** Update developer ad-earnings activation and optional title provider ID. */
+    static updateSettings<T>(title_id: string, data: object): AxiosPromise<Response<T>>;
+    /** Resolve ad eligibility and create an expiring provider manifest/session. */
+    static createSession<T>(title_id: string, data: object): AxiosPromise<Response<T>>;
+    /** Store one normalized, idempotent event for an advertising session. */
+    static storeEvent<T>(title_id: string, session_id: string, data: GameAdEventPayload): AxiosPromise<Response<T>>;
+    /** Return developer-visible estimated/finalized earnings and delivery totals. */
+    static revenueSummary<T>(title_id: string, params?: Record<string, any>): AxiosPromise<Response<T>>;
+    /** Return every intrinsic-ad surface configured for a title. */
+    static inGamePlacements<T>(title_id: string): AxiosPromise<Response<T>>;
+    /** Atomically replace a title's provider-neutral intrinsic-ad surfaces. */
+    static replaceInGamePlacements<T>(title_id: string, placements: GameInGameAdPlacement[]): AxiosPromise<Response<T>>;
+    /** Return site-admin delivery settings, aggregate metrics, and recent revenue. */
+    static adminDashboard<T>(): AxiosPromise<Response<T>>;
+    /** Partially update platform-wide providers and delivery frequency. */
+    static adminUpdateSettings<T>(data: object): AxiosPromise<Response<T>>;
+    /** Import or reconcile one provider revenue report row. */
+    static adminStoreRevenue<T>(data: object): AxiosPromise<Response<T>>;
+    /** Return public provider app keys and platform mappings for site admins. */
+    static adminProviderApps<T>(): AxiosPromise<Response<T>>;
+    /** Create or update a provider app mapping without accepting report secrets. */
+    static adminUpsertProviderApp<T>(data: GameAdProviderApp): AxiosPromise<Response<T>>;
+}
+
 interface Route {
     url: string;
     method: string;
@@ -11397,6 +11528,7 @@ declare class Glitch {
         AdminReports: typeof AdminReports;
         AdminUsers: typeof AdminUsers;
         MarketResearch: typeof MarketResearch;
+        GameAdvertising: typeof GameAdvertising;
     };
     static util: {
         Requests: typeof Requests;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glitch-javascript-sdk",
-  "version": "3.5.3",
+  "version": "3.7.0",
   "description": "Javascript SDK for Glitch",
   "publishConfig": {
     "access": "public"
@@ -13,7 +13,7 @@
   ],
   "types": "dist/index.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node scripts/test-game-advertising-routes.cjs",
     "build": "rm -Rf dist && rollup -c --bundleConfigAsCjs",
     "build-docs": "rm  -rf docs && typedoc  --tsconfig tsconfig.json src/"
   },

package/src/api/GameAdvertising.ts

@@ -0,0 +1,130 @@
+import { AxiosPromise } from 'axios';
+import GameAdvertisingRoute from '../routes/GameAdvertisingRoute';
+import Requests from '../util/Requests';
+import Response from '../util/Response';
+
+export interface GameAdEventPayload {
+  /** Opaque token returned by the server-created advertising manifest. */
+  token: string;
+  /** Client idempotency UUID. Reuse is valid only within the same ad session. */
+  event_uuid?: string;
+  /** Provider that produced or attempted the event. */
+  provider: string;
+  /** Stable Glitch placement name, such as game_banner or game_video. */
+  placement: string;
+  /** Normalized creative/ad format. */
+  format: 'banner' | 'video' | 'interstitial' | 'rewarded' | 'in_game_image' | 'in_game_video' | 'other';
+  /** Normalized SDK/ad lifecycle event. */
+  event_type: 'sdk_ready' | 'request_started' | 'loaded' | 'channel_registered' | 'measurement' | 'no_fill' | 'fallback_shown' | 'started' | 'impression' | 'viewable' | 'clicked' | 'completed' | 'skipped' | 'closed' | 'paused_game' | 'resumed_game' | 'error';
+  /** Optional provider-native event or impression identifier. */
+  provider_event_id?: string;
+  /** Non-sensitive provider diagnostics and event context. */
+  metadata?: Record<string, any>;
+  /** ISO 8601 client-observed timestamp. Defaults to server receipt time. */
+  occurred_at?: string;
+}
+
+/** Provider-neutral intrinsic-ad surface declared by a game developer. */
+export interface GameInGameAdPlacement {
+  id?: string;
+  title_id?: string;
+  provider?: 'anzu';
+  placement_key: string;
+  channel_name: string;
+  surface_type: 'mesh' | 'sprite' | 'ui_image' | 'raw_image' | 'html' | 'electron_shell';
+  scene_name?: string | null;
+  aspect_ratio: number;
+  allow_images: boolean;
+  allow_videos: boolean;
+  allow_audio?: boolean;
+  is_dynamic: boolean;
+  is_clickable: boolean;
+  shrink_to_fit: boolean;
+  fallback_media_url?: string | null;
+  status: 'active' | 'disabled';
+  metadata?: Record<string, any> | null;
+}
+
+/** Public delivery identity for a provider and runtime platform. */
+export interface GameAdProviderApp {
+  id?: string;
+  title_id?: string | null;
+  provider: 'anzu';
+  platform: 'web' | 'electron_macos' | 'electron_windows' | 'electron_linux' | 'unity_webgl' | 'cocos_web' | 'construct_web';
+  app_key: string;
+  bundle_id?: string | null;
+  mode: 'integration' | 'production';
+  integration_type: 'managed' | 'direct';
+  status: 'active' | 'disabled' | 'pending';
+  metadata?: Record<string, any> | null;
+}
+
+/**
+ * Typed client for platform-served game advertising.
+ *
+ * These endpoints manage publisher inventory displayed around playable games;
+ * they are intentionally separate from APIs used to buy advertising campaigns.
+ */
+class GameAdvertising {
+  /** Return developer-visible ad-earnings settings for a title. */
+  public static settings<T>(title_id: string): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.settings, undefined, { title_id });
+  }
+
+  /** Update developer ad-earnings activation and optional title provider ID. */
+  public static updateSettings<T>(title_id: string, data: object): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.updateSettings, data, { title_id });
+  }
+
+  /** Resolve ad eligibility and create an expiring provider manifest/session. */
+  public static createSession<T>(title_id: string, data: object): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.createSession, data, { title_id });
+  }
+
+  /** Store one normalized, idempotent event for an advertising session. */
+  public static storeEvent<T>(title_id: string, session_id: string, data: GameAdEventPayload): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.storeEvent, data, { title_id, session_id });
+  }
+
+  /** Return developer-visible estimated/finalized earnings and delivery totals. */
+  public static revenueSummary<T>(title_id: string, params?: Record<string, any>): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.revenueSummary, undefined, { title_id }, params);
+  }
+
+  /** Return every intrinsic-ad surface configured for a title. */
+  public static inGamePlacements<T>(title_id: string): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.inGamePlacements, undefined, { title_id });
+  }
+
+  /** Atomically replace a title's provider-neutral intrinsic-ad surfaces. */
+  public static replaceInGamePlacements<T>(title_id: string, placements: GameInGameAdPlacement[]): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.replaceInGamePlacements, { placements }, { title_id });
+  }
+
+  /** Return site-admin delivery settings, aggregate metrics, and recent revenue. */
+  public static adminDashboard<T>(): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.adminDashboard);
+  }
+
+  /** Partially update platform-wide providers and delivery frequency. */
+  public static adminUpdateSettings<T>(data: object): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.adminUpdateSettings, data);
+  }
+
+  /** Import or reconcile one provider revenue report row. */
+  public static adminStoreRevenue<T>(data: object): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.adminStoreRevenue, data);
+  }
+
+  /** Return public provider app keys and platform mappings for site admins. */
+  public static adminProviderApps<T>(): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.adminProviderApps);
+  }
+
+  /** Create or update a provider app mapping without accepting report secrets. */
+  public static adminUpsertProviderApp<T>(data: GameAdProviderApp): AxiosPromise<Response<T>> {
+    return Requests.processRoute(GameAdvertisingRoute.routes.adminUpsertProviderApp, data);
+  }
+}
+
+export default GameAdvertising;

package/src/api/Titles.ts

@@ -1316,7 +1316,7 @@ class Titles {
     }
 
     /**
-     * Get a consolidated report of all earnings for a title, including 
+     * Get a consolidated report of all earnings for a title, including
      * playtime payouts, direct premium purchases, and rentals (minus refunds).
      * 
      * @param title_id The UUID of the title.

package/src/api/Users.ts

@@ -4,6 +4,54 @@ import Requests from "../util/Requests";
 import Response from "../util/Response";
 import { AxiosPromise } from "axios";
 
+/** Human-readable earning categories returned by influencer payout APIs. */
+export type InfluencerPayoutSourceType = "campaign_compensation" | "ad_revenue_share" | "subscription_residual" | "manual_adjustment";
+
+/** Auditable metrics and creator-content attribution attached to a payout. */
+export interface InfluencerPayoutBreakdown {
+    label?: string;
+    payment_method?: "flat" | "performance" | "hybrid";
+    provider?: string;
+    period_start?: string;
+    period_end?: string;
+    impressions?: number;
+    clicks?: number;
+    short_link_id?: string | null;
+    short_link_click_id?: string | null;
+    social_media_post_id?: string | null;
+    tracking_link_label?: string | null;
+    social_platform?: string | null;
+    social_post_url?: string | null;
+}
+
+/** One campaign or advertising earning payable to the authenticated influencer. */
+export interface InfluencerPayout {
+    id: string;
+    user_id: string;
+    campaign_id: string;
+    amount: number;
+    currency: string;
+    status: "pending" | "completed" | "failed";
+    payout_date?: string | null;
+    source_type: InfluencerPayoutSourceType;
+    source_label: string;
+    source_reference_id?: string | null;
+    breakdown?: InfluencerPayoutBreakdown;
+    campaign?: Record<string, any>;
+}
+
+/** Optional filters for the authenticated influencer's payout history. */
+export interface InfluencerPayoutQuery {
+    campaign_id?: string;
+    month?: number;
+    year?: number;
+    amount?: number;
+    status?: "pending" | "completed" | "failed";
+    source_type?: InfluencerPayoutSourceType;
+    orderBy?: "created_at" | "amount";
+    orderDirection?: "asc" | "desc";
+}
+
 class Users {
 
     /**
@@ -62,16 +110,17 @@ class Users {
     }
 
     /**
-     * Gets payouts from past campaings
+     * Gets the authenticated influencer's payouts from campaigns and attributed
+     * game advertising. Advertising revenue is returned as a separate additive
+     * source with provider-period metrics and tracking-link/social-post IDs.
      * 
      * @see https://api.glitch.fun/api/documentation#/Users%20Route/showMe
      * 
-     * @param user_id The id of the user to update.
-     * @param data The data to update.
+     * @param params Optional campaign, date, status, source, and ordering filters.
      * 
      * @returns promise
      */
-    public static getPayouts<T>(params?: Record<string, any>): AxiosPromise<Response<T>> {
+    public static getPayouts<T = InfluencerPayout[]>(params?: InfluencerPayoutQuery): AxiosPromise<Response<T>> {
 
         return Requests.processRoute(UserRoutes.routes.getPayouts, {}, undefined, params);
     }

package/src/api/index.ts

@@ -51,6 +51,7 @@ import PrDirectory from "./PrDirectory";
 import AdminReports from "./AdminReports";
 import AdminUsers from "./AdminUsers";
 import MarketResearch from "./MarketResearch";
+import GameAdvertising from './GameAdvertising';
 
 export {Ads};
 export {AccessKeys};
@@ -105,3 +106,4 @@ export {PrDirectory};
 export {AdminReports};
 export {AdminUsers};
 export {MarketResearch};
+export {GameAdvertising};

package/src/index.ts

@@ -55,6 +55,7 @@ import {PrDirectory} from './api';
 import {AdminReports} from './api';
 import {AdminUsers} from './api';
 import {MarketResearch} from './api';
+import {GameAdvertising} from './api';
 
 import Requests from "./util/Requests";
 import Parser from "./util/Parser";
@@ -139,6 +140,7 @@ class Glitch {
         AdminReports : AdminReports,
         AdminUsers : AdminUsers,
         MarketResearch : MarketResearch,
+        GameAdvertising: GameAdvertising,
     }
 
     public static util = {

package/src/routes/GameAdvertisingRoute.ts

@@ -0,0 +1,25 @@
+import Route from './interface';
+import HTTP_METHODS from '../constants/HttpMethods';
+
+class GameAdvertisingRoute {
+  /**
+   * Route templates for publisher game-ad inventory, telemetry, earnings, and
+   * site administration. Placeholders are expanded by Requests.processRoute.
+   */
+  public static routes: { [key: string]: Route } = {
+    settings: { url: '/titles/{title_id}/advertising/settings', method: HTTP_METHODS.GET },
+    updateSettings: { url: '/titles/{title_id}/advertising/settings', method: HTTP_METHODS.PUT },
+    createSession: { url: '/titles/{title_id}/advertising/sessions', method: HTTP_METHODS.POST },
+    storeEvent: { url: '/titles/{title_id}/advertising/sessions/{session_id}/events', method: HTTP_METHODS.POST },
+    revenueSummary: { url: '/titles/{title_id}/advertising/revenue-summary', method: HTTP_METHODS.GET },
+    inGamePlacements: { url: '/titles/{title_id}/advertising/in-game/placements', method: HTTP_METHODS.GET },
+    replaceInGamePlacements: { url: '/titles/{title_id}/advertising/in-game/placements', method: HTTP_METHODS.PUT },
+    adminDashboard: { url: '/admin/game-advertising', method: HTTP_METHODS.GET },
+    adminUpdateSettings: { url: '/admin/game-advertising/settings', method: HTTP_METHODS.PUT },
+    adminStoreRevenue: { url: '/admin/game-advertising/revenue', method: HTTP_METHODS.POST },
+    adminProviderApps: { url: '/admin/game-advertising/provider-apps', method: HTTP_METHODS.GET },
+    adminUpsertProviderApp: { url: '/admin/game-advertising/provider-apps', method: HTTP_METHODS.PUT },
+  };
+}
+
+export default GameAdvertisingRoute;