Fix GraphicRepresentation types according to latest Mesh Export API docs

common/api/frontend-tiles.api.md

@@ -80,27 +80,18 @@ export type GraphicRepresentation = {
     format: GraphicRepresentationFormat;
     dataSource: DataSource;
 } & ({
-    status: Omit<GraphicRepresentationStatus, GraphicRepresentationStatus.Complete>;
+    status: Exclude<GraphicRepresentationStatus, "Complete">;
     url?: string;
 } | {
-    status: GraphicRepresentationStatus.Complete;
+    status: "Complete";
     url: string;
 });
 
 // @beta
-export type GraphicRepresentationFormat = "IMDL" | "3DTILES" | string;
+export type GraphicRepresentationFormat = "3DFT" | "3DTiles" | "CESIUM" | "IMODEL" | string;
 
 // @beta
-export enum GraphicRepresentationStatus {
-    // (undocumented)
-    Complete = "Complete",
-    // (undocumented)
-    Failed = "Failed",
-    // (undocumented)
-    InProgress = "In progress",
-    // (undocumented)
-    NotStarted = "Not started"
-}
+export type GraphicRepresentationStatus = "Complete" | "InProgress" | "Invalid" | "NotStarted";
 
 // @beta
 export function initializeFrontendTiles(options: FrontendTilesOptions): void;

common/api/summary/frontend-tiles.exports.csv

@@ -12,7 +12,7 @@ alpha;interface;GetGeoscienceTilesetArgs
 alpha;function;getGeoscienceTilesetUrl
 beta;type;GraphicRepresentation
 beta;type;GraphicRepresentationFormat
-beta;enum;GraphicRepresentationStatus
+beta;type;GraphicRepresentationStatus
 beta;function;initializeFrontendTiles
 beta;interface;MeshExport
 internal;interface;MeshExports

common/changes/@itwin/frontend-tiles/eringram-graphicrepresentation-fix_2025-01-21-17-59.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/frontend-tiles",
+      "comment": "Update GraphicRepresentationFormat type and GraphicRepresentationStatus enum to reflect the latest Mesh Export Service docs.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/frontend-tiles"
+}

extensions/frontend-tiles/src/FrontendTiles.ts

@@ -5,7 +5,7 @@
 
 import { IModelApp, IModelConnection, SpatialTileTreeReferences, SpatialViewState } from "@itwin/core-frontend";
 import { createBatchedSpatialTileTreeReferences } from "./BatchedSpatialTileTreeRefs";
-import { queryGraphicRepresentations } from "./GraphicsProvider/GraphicRepresentationProvider";
+import { queryGraphicRepresentations, QueryGraphicRepresentationsArgs } from "./GraphicsProvider/GraphicRepresentationProvider";
 import { AccessToken } from "@itwin/core-bentley";
 import { obtainIModelTilesetUrl, ObtainIModelTilesetUrlArgs } from "./GraphicsProvider/GraphicsProvider";
 
@@ -83,7 +83,7 @@ export interface QueryMeshExportsArgs {
  * @beta
  */
 export async function* queryMeshExports(args: QueryMeshExportsArgs): AsyncIterableIterator<MeshExport> {
-  const graphicsArgs = {
+  const graphicsArgs: QueryGraphicRepresentationsArgs = {
     accessToken: args.accessToken,
     sessionId: IModelApp.sessionId,
     dataSource: {
@@ -92,7 +92,7 @@ export async function* queryMeshExports(args: QueryMeshExportsArgs): AsyncIterab
       changeId: args.changesetId,
       type: "IMODEL",
     },
-    format: "IMDL",
+    format: "IMODEL",
     urlPrefix: args.urlPrefix,
     includeIncomplete: args.includeIncomplete,
     enableCDN: args.enableCDN,

extensions/frontend-tiles/src/GraphicsProvider/GraphicRepresentationProvider.ts

@@ -10,20 +10,14 @@ import { IModelApp, ITWINJS_CORE_VERSION } from "@itwin/core-frontend";
 /** The expected format of the Graphic Representation
  * @beta
  */
-/* eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents */
-export type GraphicRepresentationFormat = "IMDL" | "3DTILES" | string;
+// eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+export type GraphicRepresentationFormat = "3DFT" | "3DTiles" | "CESIUM" | "IMODEL" | string;
 
 /** Graphic representations are generated from Data Sources.
  * The status of a Graphic Representation indicates the progress of that generation process.
  * @beta
  */
-// ###TODO this needs to be expanded to include more statuses, and/or "failed" needs to be replaced with "invalid".
-export enum GraphicRepresentationStatus {
-  InProgress = "In progress",
-  Complete = "Complete",
-  NotStarted = "Not started",
-  Failed = "Failed",
-}
+export type GraphicRepresentationStatus = "Complete" | "InProgress" | "Invalid" | "NotStarted";
 
 /**
  * Represents a data source for a graphic representation.
@@ -73,10 +67,10 @@ export type GraphicRepresentation = {
    * Therefore, the url is optional if the status is not complete, and required if the status is complete.
    */
 } & ({
-  status: Omit<GraphicRepresentationStatus, GraphicRepresentationStatus.Complete>;
+  status: Exclude<GraphicRepresentationStatus, "Complete">;
   url?: string;
 } | {
-  status: GraphicRepresentationStatus.Complete;
+  status: "Complete";
   url: string;
 });
 
@@ -138,8 +132,6 @@ export async function* queryGraphicRepresentations(args: QueryGraphicRepresentat
       iModelId: string;
       changesetId: string;
       exportType: string;
-      geometryOptions: any;
-      viewDefinitionFilter: any;
     };
 
     /* eslint-disable-next-line @typescript-eslint/naming-convention */
@@ -184,21 +176,40 @@ export async function* queryGraphicRepresentations(args: QueryGraphicRepresentat
       break;
     }
 
-    const foundSources = result.exports.filter((x) => x.request.exportType === args.dataSource.type && (args.includeIncomplete || x.status === GraphicRepresentationStatus.Complete));
+    const foundSources = result.exports.filter((x) => x.request.exportType === args.dataSource.type && (args.includeIncomplete || x.status === "Complete"));
     for (const foundSource of foundSources) {
-      const graphicRepresentation: GraphicRepresentation = {
-        displayName: foundSource.displayName,
-        representationId: foundSource.id,
-        status: foundSource.status,
-        format: args.format,
-        url: foundSource._links?.mesh.href,
-        dataSource: {
-          iTwinId: args.dataSource.iTwinId,
-          id: foundSource.request.iModelId,
-          changeId: foundSource.request.changesetId,
-          type: foundSource.request.exportType,
-        },
-      };
+      let graphicRepresentation: GraphicRepresentation;
+      if (foundSource.status === "Complete") {
+        // If the service response's status is complete, it's guaranteed to have a url defined in links.mesh.
+        graphicRepresentation = {
+          displayName: foundSource.displayName,
+          representationId: foundSource.id,
+          status: foundSource.status,
+          format: args.format,
+          url: foundSource._links!.mesh.href,
+          dataSource: {
+            iTwinId: args.dataSource.iTwinId,
+            id: foundSource.request.iModelId,
+            changeId: foundSource.request.changesetId,
+            type: foundSource.request.exportType,
+          },
+        };
+      } else {
+        // Otherwise the url may be undefined because the representation is not finished being generated
+        graphicRepresentation = {
+          displayName: foundSource.displayName,
+          representationId: foundSource.id,
+          status: foundSource.status,
+          format: args.format,
+          url: foundSource._links?.mesh.href,
+          dataSource: {
+            iTwinId: args.dataSource.iTwinId,
+            id: foundSource.request.iModelId,
+            changeId: foundSource.request.changesetId,
+            type: foundSource.request.exportType,
+          },
+        };
+      }
 
       yield graphicRepresentation;
     }

extensions/frontend-tiles/src/GraphicsProvider/GraphicsProvider.ts

@@ -5,7 +5,7 @@
 
 import { AccessToken, Logger } from "@itwin/core-bentley";
 import { IModelApp } from "@itwin/core-frontend";
-import { obtainGraphicRepresentationUrl } from "./GraphicRepresentationProvider";
+import { obtainGraphicRepresentationUrl, ObtainGraphicRepresentationUrlArgs } from "./GraphicRepresentationProvider";
 import { loggerCategory } from "../LoggerCategory";
 
 /** Arguments supplied  to [[obtainIModelTilesetUrl]].
@@ -48,7 +48,7 @@ export async function obtainIModelTilesetUrl(args: ObtainIModelTilesetUrlArgs):
     return undefined;
   }
 
-  const graphicsArgs = {
+  const graphicsArgs: ObtainGraphicRepresentationUrlArgs = {
     accessToken: args.accessToken,
     sessionId: IModelApp.sessionId,
     dataSource: {
@@ -57,7 +57,7 @@ export async function obtainIModelTilesetUrl(args: ObtainIModelTilesetUrlArgs):
       changeId: args.changesetId,
       type: "IMODEL",
     },
-    format: "IMDL",
+    format: "IMODEL",
     urlPrefix: args.urlPrefix,
     requireExactVersion: args.requireExactChangeset,
     enableCDN: args.enableCDN,

extensions/frontend-tiles/src/test/GraphicsProvider/GraphicRepresentationProvider.test.ts

@@ -7,7 +7,7 @@ import { expect, use } from "chai";
 import * as chaiAsPromised from "chai-as-promised";
 import * as sinon from "sinon";
 import { IModelApp } from "@itwin/core-frontend";
-import { createGraphicRepresentationsQueryUrl, obtainGraphicRepresentationUrl, queryGraphicRepresentations, QueryGraphicRepresentationsArgs } from "../../GraphicsProvider/GraphicRepresentationProvider";
+import { createGraphicRepresentationsQueryUrl, GraphicRepresentationFormat, obtainGraphicRepresentationUrl, queryGraphicRepresentations, QueryGraphicRepresentationsArgs } from "../../GraphicsProvider/GraphicRepresentationProvider";
 
 use(chaiAsPromised);
 
@@ -113,7 +113,17 @@ async function makeSourcesResponse(props: SourcesProps): Promise<Response> {
   return makeResponse(async () => Promise.resolve(makeSources(props)));
 }
 
-const testArgs = {
+const testArgs: {
+  accessToken: string;
+  sessionId: string;
+  dataSource: {
+    iTwinId: string;
+    id: string;
+    changeId?: string;
+    type: string;
+  };
+  format: GraphicRepresentationFormat;
+} = {
   accessToken: "this-is-a-fake-access-token",
   sessionId: "testSession",
   dataSource: {
@@ -122,7 +132,7 @@ const testArgs = {
     changeId: undefined,
     type: "srcType",
   },
-  format: "IMDL",
+  format: "IMODEL",
 };
 
 describe("queryGraphicRepresentations", () => {
@@ -144,7 +154,11 @@ describe("queryGraphicRepresentations", () => {
 
   it("produces one set of results", async () => {
     await mockFetch(
-      async () => makeSourcesResponse({ exports: [{ id: "a" }, { id: "b" }, { id: "c" }] }),
+      async () => makeSourcesResponse({ exports: [
+        { id: "a", href: "http://tiles.com/a" },
+        { id: "b", href: "http://tiles.com/b" },
+        { id: "c", href: "http://tiles.com/c" }
+      ] }),
       async () => expectSources(["a", "b", "c"], testArgs),
     );
   });
@@ -155,20 +169,32 @@ describe("queryGraphicRepresentations", () => {
       async () => {
         if (!fetchedFirst) {
           fetchedFirst = true;
-          return makeSourcesResponse({ exports: [{ id: "a" }, { id: "b" }], next: "next.org" });
+          return makeSourcesResponse({ exports: [
+              { id: "a", href: "http://tiles.com/a" },
+              { id: "b", href: "http://tiles.com/b" },
+            ],
+            next: "next.org"
+          });
         } else {
-          return makeSourcesResponse({ exports: [{ id: "c" }, { id: "d" }] });
+          return makeSourcesResponse({ exports: [
+            { id: "c", href: "http://tiles.com/c" },
+            { id: "d", href: "http://tiles.com/d" }
+          ] });
         }
       },
       async () => expectSources(["a", "b", "c", "d"], testArgs));
   });
 
   it("includes only completed Data Sources unless otherwise specified", async () => {
     await mockFetch(
-      async () => makeSourcesResponse({ exports: [{ id: "a", status: "Complete" }, { id: "b", status: "Feeling Blessed" }] }),
+      async () => makeSourcesResponse({ exports: [
+        { id: "a", status: "Complete", href: "http://tiles.com/a" },
+        { id: "b", status: "InProgress" },
+        { id: "c", status: "Invalid" }
+      ] }),
       async () => {
         await expectSources(["a"], testArgs);
-        await expectSources(["a", "b"], { ...testArgs, includeIncomplete: true }),
+        await expectSources(["a", "b", "c"], { ...testArgs, includeIncomplete: true }),
         await expectSources(["a"], { ...testArgs, includeIncomplete: false });
       },
     );
@@ -216,7 +242,7 @@ describe("obtainGraphicRepresentationUrl", () => {
             changeId: args.versionId,
             type: "srcType",
           },
-          format: "IMDL",
+          format: "IMODEL",
           requireExactVersion: args.exact,
         });