glitch-javascript-sdk 3.2.32 → 3.3.0

package/dist/index.d.ts

@@ -9009,6 +9009,243 @@ interface MultiplayerVoicePollRequest {
     limit?: number;
     exclude_self?: boolean;
 }
+type MultiplayerRealmStatus = 'active' | 'locked' | 'maintenance' | 'full' | 'offline';
+type MultiplayerZoneType = 'overworld' | 'city' | 'dungeon' | 'raid' | 'arena' | 'instanced';
+type MultiplayerInstanceKind = 'persistent' | 'dynamic' | 'dungeon' | 'raid' | 'arena';
+type MultiplayerInstanceState = 'provisioning' | 'active' | 'draining' | 'closed';
+type MultiplayerPresenceStatus = 'online' | 'in_queue' | 'in_world' | 'away' | 'offline';
+type MultiplayerMatchmakingStatus = 'queued' | 'matched' | 'canceled' | 'expired' | 'timed_out';
+type MultiplayerBanScope = 'title' | 'realm' | 'lobby' | 'server' | 'voice';
+type MultiplayerBanSource = 'manual' | 'report' | 'anticheat' | 'automated';
+type MultiplayerRealtimeScopeType = 'lobby' | 'voice' | 'zone' | 'instance';
+/** A persistent world copy (shard). */
+interface MultiplayerRealm {
+    id: string;
+    title_id: string;
+    name: string;
+    slug?: string | null;
+    region?: string | null;
+    status: MultiplayerRealmStatus;
+    population_cap: number;
+    current_population: number;
+    recommended: boolean;
+    ruleset: MultiplayerMetadata;
+    metadata: MultiplayerMetadata;
+    last_activity_at?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+}
+/** A named area within a realm (map/continent/dungeon template). */
+interface MultiplayerZone {
+    id: string;
+    title_id: string;
+    realm_id: string;
+    zone_key: string;
+    display_name: string;
+    zone_type: MultiplayerZoneType;
+    is_instanced: boolean;
+    max_players_per_instance: number;
+    min_instances: number;
+    grid_cell_size: number;
+    coordinates_bounds: MultiplayerMetadata;
+    metadata: MultiplayerMetadata;
+    created_at?: string | null;
+    updated_at?: string | null;
+}
+/** A runtime copy of a zone, optionally bound to a game server. */
+interface MultiplayerInstance {
+    id: string;
+    title_id: string;
+    realm_id: string;
+    zone_id: string;
+    server_id?: string | null;
+    instance_kind: MultiplayerInstanceKind;
+    state: MultiplayerInstanceState;
+    layer: number;
+    difficulty?: string | null;
+    max_players: number;
+    current_players: number;
+    metadata: MultiplayerMetadata;
+    last_heartbeat_at?: string | null;
+    expires_at?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    server?: MultiplayerServer | null;
+}
+/** Authoritative location of a player. */
+interface MultiplayerPresence {
+    id: string;
+    title_id: string;
+    player_id: string;
+    user_id?: string | null;
+    realm_id?: string | null;
+    zone_id?: string | null;
+    instance_id?: string | null;
+    party_id?: string | null;
+    display_name?: string | null;
+    status: MultiplayerPresenceStatus;
+    rich_status?: string | null;
+    pos_x?: number | null;
+    pos_y?: number | null;
+    pos_z?: number | null;
+    heading?: number | null;
+    grid_cell?: string | null;
+    metadata: MultiplayerMetadata;
+    last_heartbeat_at?: string | null;
+    expires_at?: string | null;
+}
+interface MultiplayerMatchmakingTicket {
+    id: string;
+    title_id: string;
+    queue: string;
+    player_id: string;
+    user_id?: string | null;
+    party: string[];
+    attributes: MultiplayerMetadata;
+    skill?: number | null;
+    region?: string | null;
+    status: MultiplayerMatchmakingStatus;
+    match_id?: string | null;
+    assignment?: MultiplayerMetadata | null;
+    queued_at?: string | null;
+    matched_at?: string | null;
+    expires_at?: string | null;
+}
+interface MultiplayerBan {
+    id: string;
+    title_id: string;
+    scope: MultiplayerBanScope;
+    scope_id?: string | null;
+    player_id: string;
+    user_id?: string | null;
+    issued_by?: string | null;
+    source: MultiplayerBanSource;
+    reason?: string | null;
+    metadata: MultiplayerMetadata;
+    expires_at?: string | null;
+}
+interface MultiplayerRealmListParams {
+    region?: string;
+    status?: MultiplayerRealmStatus;
+    recommended?: boolean;
+    limit?: number;
+}
+interface MultiplayerCreateRealmRequest {
+    name: string;
+    slug?: string;
+    region?: string;
+    status?: MultiplayerRealmStatus;
+    population_cap?: number;
+    recommended?: boolean;
+    ruleset?: MultiplayerMetadata;
+    metadata?: MultiplayerMetadata;
+}
+interface MultiplayerUpdateRealmRequest extends Partial<MultiplayerCreateRealmRequest> {
+}
+interface MultiplayerZoneListParams {
+    zone_type?: MultiplayerZoneType;
+    limit?: number;
+}
+interface MultiplayerCreateZoneRequest {
+    zone_key: string;
+    display_name: string;
+    zone_type?: MultiplayerZoneType;
+    is_instanced?: boolean;
+    max_players_per_instance?: number;
+    min_instances?: number;
+    grid_cell_size?: number;
+    coordinates_bounds?: MultiplayerMetadata;
+    metadata?: MultiplayerMetadata;
+}
+interface MultiplayerInstanceListParams {
+    state?: MultiplayerInstanceState;
+    limit?: number;
+}
+interface MultiplayerEnterZoneRequest {
+    player_id?: string;
+    realm_id: string;
+    zone_id: string;
+    server_id?: string;
+    party_id?: string;
+    instance_kind?: MultiplayerInstanceKind;
+    difficulty?: string;
+    display_name?: string;
+    rich_status?: string;
+    pos_x?: number;
+    pos_y?: number;
+    pos_z?: number;
+    heading?: number;
+    metadata?: MultiplayerMetadata;
+    instance_metadata?: MultiplayerMetadata;
+    ttl_minutes?: number;
+}
+interface MultiplayerEnterZoneResponse {
+    instance: MultiplayerInstance;
+    presence: MultiplayerPresence;
+}
+interface MultiplayerUpdatePresenceRequest {
+    player_id?: string;
+    status?: MultiplayerPresenceStatus;
+    rich_status?: string;
+    pos_x?: number;
+    pos_y?: number;
+    pos_z?: number;
+    heading?: number;
+    ttl_minutes?: number;
+}
+interface MultiplayerLeaveWorldRequest {
+    player_id?: string;
+}
+interface MultiplayerInstancePresenceParams {
+    grid_cell?: string;
+    radius?: number;
+    limit?: number;
+}
+interface MultiplayerEnqueueTicketRequest {
+    player_id?: string;
+    queue: string;
+    party?: string[];
+    attributes?: MultiplayerMetadata;
+    skill?: number;
+    region?: string;
+    ttl_seconds?: number;
+}
+interface MultiplayerBanListParams {
+    scope?: MultiplayerBanScope;
+    player_id?: string;
+    source?: MultiplayerBanSource;
+    active_only?: boolean;
+    limit?: number;
+}
+interface MultiplayerCreateBanRequest {
+    player_id: string;
+    scope?: MultiplayerBanScope;
+    scope_id?: string;
+    user_id?: string;
+    source?: MultiplayerBanSource;
+    reason?: string;
+    metadata?: MultiplayerMetadata;
+    expires_at?: string;
+}
+interface MultiplayerDeleteBanResponse {
+    deleted: boolean;
+}
+interface MultiplayerRealtimeScope {
+    type: MultiplayerRealtimeScopeType;
+    id: string;
+}
+interface MultiplayerRealtimeNegotiateRequest {
+    player_id?: string;
+    scopes?: MultiplayerRealtimeScope[];
+}
+interface MultiplayerRealtimeNegotiateResponse {
+    protocol: string;
+    url: string | null;
+    configured: boolean;
+    groups: string[];
+    access_token: string | null;
+    expires_at: string | null;
+}
 /**
  * Steam-style multiplayer APIs for Glitch titles.
  *
@@ -9443,6 +9680,184 @@ declare class Multiplayer {
      * @param params Optional player_id for title-token clients.
      */
     static deleteFavorite<T = MultiplayerDeleteFavoriteResponse>(title_id: string, favorite_id: string, params?: MultiplayerDeleteFavoriteParams): AxiosPromise<Response<T>>;
+    /**
+     * List realms (persistent world shards) so a player can choose where to log in.
+     *
+     * @param title_id Title UUID.
+     * @param params Optional region/status filters; recommended realms sort first.
+     * @example
+     * Multiplayer.listRealms('title-uuid', { region: 'us-central', status: 'active' });
+     */
+    static listRealms<T = MultiplayerRealm[]>(title_id: string, params?: MultiplayerRealmListParams): AxiosPromise<Response<T>>;
+    /**
+     * Create a realm. Requires a title administrator JWT.
+     *
+     * @param title_id Title UUID.
+     * @param data Realm configuration.
+     * @example
+     * Multiplayer.createRealm('title-uuid', { name: 'Aurora', region: 'us-central', population_cap: 5000, recommended: true });
+     */
+    static createRealm<T = MultiplayerRealm>(title_id: string, data: MultiplayerCreateRealmRequest): AxiosPromise<Response<T>>;
+    /**
+     * Retrieve a single realm.
+     *
+     * @param title_id Title UUID.
+     * @param realm_id Realm UUID.
+     */
+    static showRealm<T = MultiplayerRealm>(title_id: string, realm_id: string): AxiosPromise<Response<T>>;
+    /**
+     * Update a realm (status, population cap, ruleset). Requires a title admin JWT.
+     *
+     * @param title_id Title UUID.
+     * @param realm_id Realm UUID.
+     * @param data Fields to update.
+     */
+    static updateRealm<T = MultiplayerRealm>(title_id: string, realm_id: string, data: MultiplayerUpdateRealmRequest): AxiosPromise<Response<T>>;
+    /**
+     * List the zones defined for a realm.
+     *
+     * @param title_id Title UUID.
+     * @param realm_id Realm UUID.
+     * @param params Optional zone_type filter.
+     */
+    static listZones<T = MultiplayerZone[]>(title_id: string, realm_id: string, params?: MultiplayerZoneListParams): AxiosPromise<Response<T>>;
+    /**
+     * Create a zone in a realm. Requires a title administrator JWT.
+     *
+     * @param title_id Title UUID.
+     * @param realm_id Realm UUID.
+     * @param data Zone configuration, including interest-management grid cell size.
+     * @example
+     * Multiplayer.createZone('title-uuid', 'realm-uuid', {
+     *   zone_key: 'ashfall_valley',
+     *   display_name: 'Ashfall Valley',
+     *   zone_type: 'overworld',
+     *   max_players_per_instance: 100,
+     *   grid_cell_size: 64
+     * });
+     */
+    static createZone<T = MultiplayerZone>(title_id: string, realm_id: string, data: MultiplayerCreateZoneRequest): AxiosPromise<Response<T>>;
+    /**
+     * List the active/other instances (runtime copies) of a zone.
+     *
+     * @param title_id Title UUID.
+     * @param zone_id Zone UUID.
+     * @param params Optional state filter.
+     */
+    static listInstances<T = MultiplayerInstance[]>(title_id: string, zone_id: string, params?: MultiplayerInstanceListParams): AxiosPromise<Response<T>>;
+    /**
+     * Retrieve a single instance.
+     *
+     * @param title_id Title UUID.
+     * @param instance_id Instance UUID.
+     */
+    static showInstance<T = MultiplayerInstance>(title_id: string, instance_id: string): AxiosPromise<Response<T>>;
+    /**
+     * List players present in an instance. Pass grid_cell (and optional radius) to
+     * receive only players in the caller's area of interest — the key to keeping
+     * per-player fan-out bounded regardless of how populated the zone is.
+     *
+     * @param title_id Title UUID.
+     * @param instance_id Instance UUID.
+     * @param params grid_cell "cx:cy" and radius (0-4) to scope the query.
+     * @example
+     * Multiplayer.listInstancePresence('title-uuid', 'instance-uuid', { grid_cell: '12:8', radius: 1 });
+     */
+    static listInstancePresence<T = MultiplayerPresence[]>(title_id: string, instance_id: string, params?: MultiplayerInstancePresenceParams): AxiosPromise<Response<T>>;
+    /**
+     * Enter a zone. The backend places the player into an active instance with
+     * capacity (creating a new layer if all are full), enforces bans and realm
+     * capacity, and upserts presence. Returns the instance and presence so the
+     * client can connect and subscribe to the instance's real-time group.
+     *
+     * @param title_id Title UUID.
+     * @param data Realm/zone target plus optional spawn position and metadata.
+     * @example
+     * Multiplayer.enterZone('title-uuid', {
+     *   player_id: 'steam:765...',
+     *   realm_id: 'realm-uuid',
+     *   zone_id: 'zone-uuid',
+     *   pos_x: 128.0, pos_z: 64.0
+     * });
+     */
+    static enterZone<T = MultiplayerEnterZoneResponse>(title_id: string, data: MultiplayerEnterZoneRequest): AxiosPromise<Response<T>>;
+    /**
+     * Update presence (position, heading, rich status) and refresh the TTL. Call
+     * on a movement interval and on notable state changes.
+     *
+     * @param title_id Title UUID.
+     * @param data New position/status for the player.
+     */
+    static updatePresence<T = MultiplayerPresence>(title_id: string, data: MultiplayerUpdatePresenceRequest): AxiosPromise<Response<T>>;
+    /**
+     * Leave the world. Frees the player's instance slot and realm population.
+     *
+     * @param title_id Title UUID.
+     * @param data Optional player_id for title-token clients.
+     */
+    static leaveWorld<T = MultiplayerPresence>(title_id: string, data?: MultiplayerLeaveWorldRequest): AxiosPromise<Response<T>>;
+    /**
+     * Enqueue a matchmaking ticket. Idempotent per (queue, player): an existing
+     * open ticket is returned rather than duplicated, so retries are safe. Poll
+     * the ticket or subscribe to `matchmaking.matched` for the assignment.
+     *
+     * @param title_id Title UUID.
+     * @param data Queue name plus optional party, skill, region, and attributes.
+     * @example
+     * Multiplayer.enqueueTicket('title-uuid', { player_id: 'steam:765...', queue: 'ranked_2v2', skill: 1840, region: 'us-central' });
+     */
+    static enqueueTicket<T = MultiplayerMatchmakingTicket>(title_id: string, data: MultiplayerEnqueueTicketRequest): AxiosPromise<Response<T>>;
+    /**
+     * Poll a matchmaking ticket. A queued ticket past its TTL is reported as
+     * `timed_out`; a matched ticket carries the connection `assignment`.
+     *
+     * @param title_id Title UUID.
+     * @param ticket_id Ticket UUID.
+     */
+    static showTicket<T = MultiplayerMatchmakingTicket>(title_id: string, ticket_id: string): AxiosPromise<Response<T>>;
+    /**
+     * Cancel a queued matchmaking ticket.
+     *
+     * @param title_id Title UUID.
+     * @param ticket_id Ticket UUID.
+     */
+    static cancelTicket<T = MultiplayerMatchmakingTicket>(title_id: string, ticket_id: string): AxiosPromise<Response<T>>;
+    /**
+     * Negotiate a real-time push connection. Returns the authorized group names
+     * and the push endpoint. When SignalR/Web PubSub is configured, an
+     * access_token scoped to those groups is included; otherwise `configured` is
+     * false and the client should fall back to the polling endpoints.
+     *
+     * @param title_id Title UUID.
+     * @param data Optional player_id and the scopes (lobby/voice/zone/instance) to subscribe to.
+     * @example
+     * Multiplayer.negotiateRealtime('title-uuid', { player_id: 'steam:765...', scopes: [{ type: 'instance', id: 'instance-uuid' }] });
+     */
+    static negotiateRealtime<T = MultiplayerRealtimeNegotiateResponse>(title_id: string, data?: MultiplayerRealtimeNegotiateRequest): AxiosPromise<Response<T>>;
+    /**
+     * List bans for a title. Requires a title administrator JWT.
+     *
+     * @param title_id Title UUID.
+     * @param params Optional scope/player/source filters and active_only.
+     */
+    static listBans<T = MultiplayerBan[]>(title_id: string, params?: MultiplayerBanListParams): AxiosPromise<Response<T>>;
+    /**
+     * Ban a player at a scope (title/realm/lobby/server/voice). Requires a title
+     * administrator JWT. Omit expires_at for a permanent ban.
+     *
+     * @param title_id Title UUID.
+     * @param data Ban target and scope.
+     * @example
+     * Multiplayer.createBan('title-uuid', { player_id: 'steam:765...', scope: 'title', reason: 'Cheating: aimbot' });
+     */
+    static createBan<T = MultiplayerBan>(title_id: string, data: MultiplayerCreateBanRequest): AxiosPromise<Response<T>>;
+    /**
+     * Lift a ban. Requires a title administrator JWT.
+     *
+     * @param title_id Title UUID.
+     * @param ban_id Ban UUID.
+     */
+    static deleteBan<T = MultiplayerDeleteBanResponse>(title_id: string, ban_id: string): AxiosPromise<Response<T>>;
 }
 
 declare class ServerOperations {

package/package.json

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