glitch-javascript-sdk 3.6.0 → 3.7.0

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

@@ -1,5 +1,9 @@
 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;
     };

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.
      *
@@ -11028,25 +11073,89 @@ declare class MarketResearch {
 }
 
 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;
-    format: 'banner' | 'video' | 'interstitial' | 'rewarded' | 'other';
-    event_type: 'sdk_ready' | 'request_started' | 'loaded' | 'no_fill' | 'started' | 'impression' | 'viewable' | 'clicked' | 'completed' | 'skipped' | 'closed' | 'paused_game' | 'resumed_game' | 'error';
+    /** 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glitch-javascript-sdk",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Javascript SDK for Glitch",
   "publishConfig": {
     "access": "public"

package/src/api/GameAdvertising.ts

@@ -4,49 +4,127 @@ 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;
-  format: 'banner' | 'video' | 'interstitial' | 'rewarded' | 'other';
-  event_type: 'sdk_ready' | 'request_started' | 'loaded' | 'no_fill' | 'started' | 'impression' | 'viewable' | 'clicked' | 'completed' | 'skipped' | 'closed' | 'paused_game' | 'resumed_game' | 'error';
+  /** 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/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/routes/GameAdvertisingRoute.ts

@@ -2,15 +2,23 @@ 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 },
   };
 }