Remove putScene method

.changeset/funny-impalas-post.md

@@ -0,0 +1,6 @@
+---
+"@itwin/scenes-client": minor
+---
+
+**BREAKING CHANGE**: Remove `putScene` operation and related types (`PutSceneParams`, `SceneUpsert`).
+  - Consumers can use `patchScene` to update scene metadata or `patchObjectsOperations` to make atomic changes to scene data.

packages/scenes-client/README.md

@@ -111,26 +111,6 @@ const createResponse = await client.postScene({
 console.log(`Created scene: ${createResponse.scene!.displayName}`);
 ```
 
-#### Replace a Scene
-
-```ts
-// Fully replace an existing scene by id. Will create a new scene if provided sceneId does not exist.
-const putResponse = await client.putScene({
-  iTwinId: "<itwin_id>",
-  sceneId: "<scene_id>",
-  scene: {
-    displayName: "Full Scene Payload",
-    sceneData: {
-      objects: [
-        /** (optional) full list of scene objects */
-      ],
-    },
-  },
-});
-
-console.log(`Created or replaced scene: ${putResponse.scene!.displayName}`);
-```
-
 #### Update a Scene's metadata
 
 ```ts

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

@@ -19,7 +19,6 @@ import {
   GetSceneMetadataParams,
   isSceneMetadataResponse,
   SceneMetadataResponse,
-  PutSceneParams,
 } from "../models/index.js";
 import { iteratePagedEndpoint } from "../utilities.js";
 import { callApi, AuthArgs } from "./apiFetch.js";
@@ -180,35 +179,6 @@ 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,
-    typeGuard: isSceneResponse,
-    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,7 +10,6 @@ import {
   deleteScene,
   getScenes,
   getSceneMetadata,
-  putScene,
 } from "./api/sceneApi.js";
 import {
   postObjects,
@@ -52,7 +51,6 @@ import {
   PatchObjectParam,
   GetSceneMetadataParams,
   SceneMetadataResponse,
-  PutSceneParams,
   PatchObjectsOperationsParams,
   GetTagParams,
   GetTagsParams,
@@ -178,25 +176,7 @@ export class SceneClient {
   }
 
   /**
-   * 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}.
+   * Update an existing scene's metadata.
    * @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

@@ -9,7 +9,6 @@ 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";
 import { GetTagsOptions } from "./tag/getTagsOptions.js";
 import { TagCreate } from "./tag/tagCreate.js";
 import { TagUpdate } from "./tag/tagUpdate.js";
@@ -24,7 +23,6 @@ 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

@@ -22,7 +22,6 @@ 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 "./tag/getTagsOptions.js";

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

@@ -43,7 +43,7 @@ const REPO_OBJ: SceneObjectCreate = {
     iTwinId: ITWIN_ID,
     id: IMODEL_ID,
     class: "iModels",
-    repositoryId: "iModels",
+    repositoryId: "imodels",
   },
 };
 
@@ -174,32 +174,6 @@ 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({
@@ -468,7 +442,7 @@ describe("Tag operations", () => {
     expect(found).toBe(true);
   });
 
-  it("scene create/update/upsert with tagIds", async () => {
+  it("scene create/update with tagIds", async () => {
     const created = await client.postScene({
       iTwinId: ITWIN_ID,
       scene: {
@@ -488,16 +462,6 @@ describe("Tag operations", () => {
       },
     });
     expect(patched.scene.tags).toStrictEqual([]);
-
-    const upserted = await client.putScene({
-      iTwinId: ITWIN_ID,
-      sceneId,
-      scene: {
-        displayName: "TaggedSceneB",
-        tagIds: [tagId],
-      },
-    });
-    expect(upserted.scene.tags.map((t) => t.id)).toContain(tagId);
   });
 
   it("delete tag removes it", async () => {

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

@@ -149,27 +149,6 @@ 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);
@@ -546,15 +525,6 @@ 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: () =>