@crowdedkingdomstudios/crowdyjs 4.3.0 → 5.0.1

package/MIGRATION.md

@@ -1,3 +1,33 @@
+# CrowdyJS v5 Migration Notes
+
+CrowdyJS v5 makes the realtime subscription **app-scoped** to fix a cross-app
+notification leak: a single game token is app-agnostic and one UDP proxy
+session is shared by every subscription on that token, so a token reused across
+apps (e.g. a player in multiple tabs/apps) used to receive other apps' spatial
+fan-out.
+
+## Breaking change
+
+- `client.udp.subscribe(handlers, appId)` — **`appId` is now required**. The
+  game-api fences `udpNotifications` by app and **rejects app-agnostic
+  subscriptions** with a `RealtimeConnectionEvent` `code = 'APP_ID_REQUIRED'`.
+
+  ```ts
+  // Before (v4):
+  client.udp.subscribe({ actorUpdate });
+  // After (v5):
+  client.udp.subscribe({ actorUpdate }, '1');
+  // Or use the world helper, which passes its appId automatically:
+  client.world('1').subscribe({ actorUpdate });
+  ```
+
+  Run one client per app (sharing the same `tokenStore`) when a player is in
+  multiple apps at once.
+
+- Requires a game-api that enforces the app fence (`cks-game-api >= v0.9.0`).
+
+---
+
 # CrowdyJS v3 Migration Notes
 
 CrowdyJS v3 is a breaking rewrite focused on browser game clients.

package/README.md

@@ -65,7 +65,7 @@ Auth and user reads always target `managementUrl`. Everything else targets `http
 ## Game-loop lifecycle
 
 1. Authenticate with `client.auth.login()` or restore a previous token through `client.session.restore()`.
-2. Subscribe to UDP proxy notifications with `client.udp.subscribe()` (the SDK will open the realtime socket on demand).
+2. Subscribe to UDP proxy notifications with `client.udp.subscribe(handlers, appId)` — `appId` is **required** (the SDK opens the realtime socket on demand and scopes it to that app).
 3. Join a chunk by sending an initial actor update.
 4. Send actor, voxel, text, audio, and client-event updates through `client.udp` or the higher-level `client.world(appId)` helpers.
 5. Call `client.udp.disconnect()` when leaving the world.
@@ -76,43 +76,63 @@ Auth and user reads always target `managementUrl`. Everything else targets `http
 When a player is about to join an app, query its routing fields on the management API first:
 
 ```graphql
-query AppForRouting($id: BigInt!) {
-  app(id: $id) {
+query AppForRouting($appId: BigInt!) {
+  app(appId: $appId) {
     appId
     splitMode
+    deploymentTarget
     gameApiUrl
   }
 }
 ```
 
-If `splitMode && gameApiUrl`, the app lives behind its own Game API deployment. Build a **second** `CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) **sharing the same `tokenStore` as the first client**, then drive gameplay through that client. Apps without `splitMode` keep working against the default `httpUrl` you configured.
+`gameApiUrl` is populated for **both** dedicated (`splitMode`) and shared
+(`deploymentTarget: "shared"`) apps. When it's set, build a **second**
+`CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) **sharing the
+same `tokenStore` as the first client**, then drive gameplay through that client.
+Apps with no `gameApiUrl` keep working against the default `httpUrl` you
+configured.
 
 ## Realtime notifications
 
+`subscribe` takes the handlers **and a required `appId`** (second argument). The
+Game API scopes the realtime session to that app and rejects an app-agnostic
+subscription with a `RealtimeConnectionEvent` (`code: 'APP_ID_REQUIRED'`). Run
+one client per app (sharing the same `tokenStore`) when a player is in multiple
+apps at once.
+
 ```ts
-const unsubscribe = client.udp.subscribe({
-  actorUpdate: (event) => {
-    console.log(event.uuid, event.state);
-  },
-  voxelUpdate: (event) => { /* ... */ },
-  text: (event) => { /* ... */ },
-  audio: (event) => { /* ... */ },
-  clientEvent: (event) => { /* ... */ },
-  serverEvent: (event) => { /* ... */ },
-  singleActorMessage: (event) => {
-    // A direct actor-to-actor message addressed to you.
-    console.log(event.uuid, event.payload); // payload is base64
-  },
-  genericError: (event) => {
-    console.warn(event.sequenceNumber, event.errorCode);
-  },
-  connectionEvent: (event) => {
-    console.warn(event.code, event.message);
+const appId = '1';
+
+const unsubscribe = client.udp.subscribe(
+  {
+    actorUpdate: (event) => {
+      console.log(event.uuid, event.state);
+    },
+    voxelUpdate: (event) => { /* ... */ },
+    text: (event) => { /* ... */ },
+    audio: (event) => { /* ... */ },
+    clientEvent: (event) => { /* ... */ },
+    serverEvent: (event) => { /* ... */ },
+    singleActorMessage: (event) => {
+      // A direct actor-to-actor message addressed to you.
+      console.log(event.uuid, event.payload); // payload is base64
+    },
+    genericError: (event) => {
+      console.warn(event.sequenceNumber, event.errorCode);
+    },
+    connectionEvent: (event) => {
+      console.warn(event.code, event.message);
+    },
+    error: (error) => {
+      console.error(error.code, error.message);
+    },
   },
-  error: (error) => {
-    console.error(error.code, error.message);
-  },
-});
+  appId,
+);
+
+// Or use the world helper, which passes its appId automatically:
+//   client.world(appId).subscribe(handlers);
 
 client.realtime.onStatus((status) => {
   console.log('realtime:', status);

package/dist/domains/udp.d.ts

@@ -54,12 +54,16 @@ export declare class UdpAPI {
      */
     sendChannelMessage(input: SendChannelMessageMutationVariables['input']): Promise<boolean>;
     /**
-     * Subscribe to udpNotifications. Pass any combination of typename
-     * handlers; the returned function detaches all of them. The first
-     * subscriber opens the shared WebSocket; the last one to leave closes
-     * it.
+     * Subscribe to udpNotifications for a single app. Pass any combination of
+     * typename handlers; the returned function detaches all of them. The first
+     * subscriber opens the shared WebSocket; the last one to leave closes it.
+     *
+     * `appId` is required and scopes the subscription to one app: the game-api
+     * only delivers that app's spatial notifications and rejects app-agnostic
+     * subscriptions (a single game token reused across apps would otherwise
+     * cross-deliver). Use a separate client per app (sharing the token store).
      */
-    subscribe(handlers: UdpNotificationHandlers): () => void;
+    subscribe(handlers: UdpNotificationHandlers, appId: string): () => void;
     private withSequence;
 }
 //# sourceMappingURL=udp.d.ts.map

package/dist/domains/udp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/domains/udp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,KAAK,uBAAuB,EAG5B,KAAK,6BAA6B,EAElC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,+BAA+B,EAEpC,KAAK,gCAAgC,EAErC,KAAK,uCAAuC,EAE5C,KAAK,mCAAmC,EACzC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1D;;;;;;GAMG;AACH,qBAAa,MAAM;IAIf,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,IAAI;IAJd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;gBAG3C,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,mBAAmB;IAG7B,OAAO,IAAI,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IAK9D,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAK9B,gBAAgB,IAAI,OAAO,CAC/B,6BAA6B,CAAC,0BAA0B,CAAC,CAC1D;IAQK,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,cAAc,CAClB,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,GAC9C,OAAO,CAAC,OAAO,CAAC;IAKb,qBAAqB,CACzB,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,EAC/C,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;OAMG;IACG,sBAAsB,CAC1B,KAAK,EAAE,uCAAuC,CAAC,OAAO,CAAC,GACtD,OAAO,CAAC,OAAO,CAAC;IAOnB;;;;;;OAMG;IACG,kBAAkB,CACtB,KAAK,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAIxD,OAAO,CAAC,YAAY;CAQrB"}
+{"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/domains/udp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,KAAK,uBAAuB,EAG5B,KAAK,6BAA6B,EAElC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,+BAA+B,EAEpC,KAAK,gCAAgC,EAErC,KAAK,uCAAuC,EAE5C,KAAK,mCAAmC,EACzC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1D;;;;;;GAMG;AACH,qBAAa,MAAM;IAIf,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,IAAI;IAJd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;gBAG3C,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,mBAAmB;IAG7B,OAAO,IAAI,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IAK9D,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAK9B,gBAAgB,IAAI,OAAO,CAC/B,6BAA6B,CAAC,0BAA0B,CAAC,CAC1D;IAQK,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,cAAc,CAClB,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,GAC9C,OAAO,CAAC,OAAO,CAAC;IAKb,qBAAqB,CACzB,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,EAC/C,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;OAMG;IACG,sBAAsB,CAC1B,KAAK,EAAE,uCAAuC,CAAC,OAAO,CAAC,GACtD,OAAO,CAAC,OAAO,CAAC;IAOnB;;;;;;OAMG;IACG,kBAAkB,CACtB,KAAK,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI;IAIvE,OAAO,CAAC,YAAY;CAQrB"}

package/dist/domains/udp.js

@@ -100,13 +100,17 @@ export class UdpAPI {
         return data.sendChannelMessage;
     }
     /**
-     * Subscribe to udpNotifications. Pass any combination of typename
-     * handlers; the returned function detaches all of them. The first
-     * subscriber opens the shared WebSocket; the last one to leave closes
-     * it.
+     * Subscribe to udpNotifications for a single app. Pass any combination of
+     * typename handlers; the returned function detaches all of them. The first
+     * subscriber opens the shared WebSocket; the last one to leave closes it.
+     *
+     * `appId` is required and scopes the subscription to one app: the game-api
+     * only delivers that app's spatial notifications and rejects app-agnostic
+     * subscriptions (a single game token reused across apps would otherwise
+     * cross-deliver). Use a separate client per app (sharing the token store).
      */
-    subscribe(handlers) {
-        return this.subs.subscribe(handlers);
+    subscribe(handlers, appId) {
+        return this.subs.subscribe(handlers, appId);
     }
     withSequence(input) {
         return {

package/dist/generated/graphql.d.ts

@@ -1663,6 +1663,12 @@ export type JoinSessionInput = {
     role?: InputMaybe<Scalars['String']['input']>;
     sessionId: Scalars['String']['input'];
 };
+export type LinkAppToEnvironmentInput = {
+    appId: Scalars['BigInt']['input'];
+    /** Environment slug (cks_environments.slug) to link the app to. */
+    environmentSlug: Scalars['String']['input'];
+    orgId: Scalars['BigInt']['input'];
+};
 export type ListVoxelUpdatesByDistanceInput = {
     appId: Scalars['BigInt']['input'];
     centerCoordinate: ChunkCoordinatesInput;
@@ -1776,6 +1782,8 @@ export type Mutation = {
     leaveChannel: Scalars['Boolean']['output'];
     /** Leave a team. */
     leaveTeam: Scalars['Boolean']['output'];
+    /** Links an unlinked app to an existing environment for split-mode routing. Refuses shared apps and apps already linked elsewhere. */
+    linkAppToEnvironment: App;
     login: AuthResponse;
     logout: Scalars['Boolean']['output'];
     logoutAllDevices: Scalars['Boolean']['output'];
@@ -2067,6 +2075,9 @@ export type MutationLeaveChannelArgs = {
 export type MutationLeaveTeamArgs = {
     groupId: Scalars['BigInt']['input'];
 };
+export type MutationLinkAppToEnvironmentArgs = {
+    input: LinkAppToEnvironmentInput;
+};
 export type MutationLoginArgs = {
     loginUserInput: LoginUserInput;
 };
@@ -2551,6 +2562,7 @@ export type Query = {
     environmentDatacenters: Array<CksOvhDatacenter>;
     /** Customer-selectable instance flavors in the datacenter with current availability and customer pricing. */
     environmentFlavors: Array<CksOvhFlavor>;
+    environmentForwardVersions: Array<CksEnvironmentVersion>;
     /** Pricing quote for the selected flavors. Fails if any flavor is unavailable, hidden, or lacks customer pricing. */
     environmentQuote: CksEnvironmentQuote;
     /** Per-app usage totals for apps linked to an environment. */
@@ -2786,6 +2798,10 @@ export type QueryEffectiveQuotaArgs = {
 export type QueryEnvironmentFlavorsArgs = {
     datacenter: Scalars['String']['input'];
 };
+export type QueryEnvironmentForwardVersionsArgs = {
+    orgId: Scalars['BigInt']['input'];
+    slug: Scalars['String']['input'];
+};
 export type QueryEnvironmentQuoteArgs = {
     input: EnvironmentQuoteInput;
 };
@@ -3028,6 +3044,7 @@ export type RedeployEnvironmentInput = {
     deployMode?: InputMaybe<RedeployDeployMode>;
     orgId: Scalars['BigInt']['input'];
     slug: Scalars['String']['input'];
+    version?: InputMaybe<Scalars['String']['input']>;
 };
 export type RegisterUserInput = {
     email: Scalars['String']['input'];