Add putScene method for full scene replacement (#86)

Author: sarah-pontier

.changeset/curly-chefs-bake.md

@@ -0,0 +1,8 @@
+---
+"@itwin/scenes-client": minor
+---
+
+Add new client method `putScene(params: PutSceneParams)`
+
+- Fully replaces an existing scene and all its objects in a single request. If the specified scene does not exist, it will be created.
+- Uses new types `SceneUpsert` and `PutSceneParams`

packages/scenes-client/src/api/sceneApi.ts

@@ -21,6 +21,7 @@ import {
   GetSceneMetadataParams,
   isSceneMetadataResponse,
   SceneMetadataResponse,
+  PutSceneParams,
 } from "../models/index.js";
 import { iteratePagedEndpoint } from "../utilities.js";
 import { callApi, AuthArgs } from "./apiFetch.js";
@@ -238,6 +239,50 @@ export async function postScene({
   });
 }
 
+/**
+ * Create or replace an existing scene.
+ * @param params - {@link PutSceneParams}
+ * @returns Created/updated scene details.
+ * @throws {ScenesApiError} If the API call fails or the response format is invalid.
+ */
+export async function putScene({
+  iTwinId,
+  sceneId,
+  scene,
+  getAccessToken,
+  baseUrl,
+}: PutSceneParams & AuthArgs): Promise<SceneResponse> {
+  return callApi<SceneResponse>({
+    endpoint: `/${sceneId}?iTwinId=${iTwinId}`,
+    getAccessToken,
+    baseUrl,
+    postProcess: async (response) => {
+      if (!response.ok) {
+        await handleErrorResponse(response);
+      }
+      const responseJson = await response.json();
+      if (!isSceneResponse(responseJson)) {
+        throw new ScenesApiError(
+          {
+            code: "InvalidResponse",
+            message: "Error creating or replacing scene: unexpected response format",
+          },
+          response.status,
+        );
+      }
+      return responseJson;
+    },
+    fetchOptions: {
+      method: "PUT",
+      body: JSON.stringify(scene),
+    },
+    additionalHeaders: {
+      Accept: "application/vnd.bentley.itwin-platform.v1+json",
+      "Content-Type": "application/json",
+    },
+  });
+}
+
 /**
  * Updates an existing scene's metadata.
  * @param params - {@link PatchSceneParams}

packages/scenes-client/src/client.ts

@@ -10,6 +10,7 @@ import {
   deleteScene,
   getScenes,
   getSceneMetadata,
+  putScene,
 } from "./api/sceneApi.js";
 import {
   postObjects,
@@ -46,6 +47,7 @@ import {
   PatchObjectParam,
   GetSceneMetadataParams,
   SceneMetadataResponse,
+  PutSceneParams,
 } from "./models/index.js";
 
 type AccessTokenFn = () => Promise<string>;
@@ -163,7 +165,25 @@ export class SceneClient {
   }
 
   /**
-   * Update an existing scene.
+   * Create or replace an existing scene and all its objects.
+   * @param params.iTwinId – The iTwin's unique identifier.
+   * @param params.sceneId – The scene's unique identifier.
+   * @param params.scene – The scene creation payload.
+   * @returns SceneResponse containing the created/updated Scene's details.
+   * @throws {ScenesApiError} If the API call fails or the response format is invalid.
+   */
+  async putScene(params: PutSceneParams): Promise<SceneResponse> {
+    return putScene({
+      iTwinId: params.iTwinId,
+      sceneId: params.sceneId,
+      scene: params.scene,
+      getAccessToken: this.getAccessToken,
+      baseUrl: this.baseUrl,
+    });
+  }
+
+  /**
+   * Update an existing scene's metadata. To replace scene objects, use {@link putScene}.
    * @param params.iTwinId – The iTwin's unique identifier.
    * @param params.sceneId – The scene's unique identifier.
    * @param params.scene – The scene update payload.

packages/scenes-client/src/models/apiParams.ts

@@ -8,6 +8,7 @@ import { BulkSceneObjectUpdate, SceneObjectUpdate } from "./object/sceneObjectUp
 import { GetScenesOptions } from "./scene/getScenesOptions.js";
 import { SceneCreate } from "./scene/sceneCreate.js";
 import { SceneUpdate } from "./scene/sceneUpdate.js";
+import { SceneUpsert } from "./scene/sceneUpsert.js";
 
 export type ITwinParams = { iTwinId: string };
 export type SceneParams = ITwinParams & { sceneId: string };
@@ -18,6 +19,7 @@ export type GetSceneParams = SceneParams & Pick<GetObjectsOptions, "orderBy">;
 export type GetScenesParams = ITwinParams & Omit<GetScenesOptions, "delayMs">;
 export type GetAllScenesParams = ITwinParams & GetScenesOptions;
 export type PostSceneParams = ITwinParams & { scene: SceneCreate };
+export type PutSceneParams = SceneParams & { scene: SceneUpsert };
 export type PatchSceneParams = SceneParams & { scene: SceneUpdate };
 export type DeleteSceneParams = SceneParams;
 

packages/scenes-client/src/models/index.ts

@@ -21,6 +21,7 @@ export * from "./scene/sceneData.js";
 export * from "./scene/sceneDataLinks.js";
 export * from "./scene/sceneMinimal.js";
 export * from "./scene/sceneUpdate.js";
+export * from "./scene/sceneUpsert.js";
 export * from "./scene/sceneWithLinks.js";
 
 export * from "./apiParams.js";

packages/scenes-client/src/models/scene/sceneUpsert.ts

@@ -0,0 +1,8 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import { SceneCreate } from "./sceneCreate.js";
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface SceneUpsert extends Omit<SceneCreate, "id"> {}

packages/scenes-client/tests/integration.test.ts

@@ -168,6 +168,32 @@ describe("Scenes operation", () => {
     expect(upd2.scene.description).toBe(undefined); // removed optional description
   });
 
+  it("replace scene", async () => {
+    const upd = await client.putScene({
+      iTwinId: ITWIN_ID,
+      sceneId: sceneAId,
+      scene: {
+        displayName: "ReplaceA",
+        description: "Description",
+        sceneData: { objects: [LAYER_OBJ] },
+      },
+    });
+
+    expect(upd.scene.displayName).toBe("ReplaceA");
+    expect(upd.scene.description).toBe("Description");
+    expect(upd.scene.sceneData.objects).toHaveLength(1);
+
+    const upd2 = await client.putScene({
+      iTwinId: ITWIN_ID,
+      sceneId: sceneAId,
+      scene: { displayName: "ReplaceB" },
+    });
+
+    expect(upd2.scene.displayName).toBe("ReplaceB");
+    expect(upd2.scene.description).toBe(undefined); // removed description
+    expect(upd2.scene.sceneData.objects).toStrictEqual([]); // removed objects
+  });
+
   it("delete scene", async () => {
     await client.deleteScene({ iTwinId: ITWIN_ID, sceneId: sceneAId });
     await expect(client.getScene({ iTwinId: ITWIN_ID, sceneId: sceneAId })).rejects.toMatchObject({

packages/scenes-client/tests/unit.test.ts

@@ -145,6 +145,27 @@ describe("Scenes Operations", () => {
     });
   });
 
+  it("putScene()", async () => {
+    fetchMock.mockImplementation(() => createSuccessfulResponse(exampleSceneResponse));
+    const client = new SceneClient(getAccessToken);
+    const scenePayload = { displayName: "My Scene", sceneData: { objects: [] } };
+    await client.putScene({
+      iTwinId: "itw-1",
+      sceneId: "scene-1",
+      scene: scenePayload,
+    });
+
+    verifyFetch(fetchMock, {
+      url: `${BASE_DOMAIN}/scene-1?iTwinId=itw-1`,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/vnd.bentley.itwin-platform.v1+json",
+      },
+      method: "PUT",
+      body: JSON.stringify(scenePayload),
+    });
+  });
+
   it("patchScene()", async () => {
     fetchMock.mockImplementation(() => createSuccessfulResponse(exampleSceneMetadataResponse));
     const client = new SceneClient(getAccessToken);
@@ -377,6 +398,15 @@ describe("Error Handling", () => {
           scene: { displayName: "Test", sceneData: { objects: [] } },
         }),
     },
+    {
+      name: "scene upsert",
+      method: () =>
+        client.putScene({
+          iTwinId: "itw-1",
+          sceneId: "scene-1",
+          scene: { displayName: "Replace", sceneData: { objects: [] } },
+        }),
+    },
     {
       name: "scene updates",
       method: () =>