Fix GraphicRepresentation types according to latest Mesh Export API docs

[eringram]

Update GraphicRepresentationFormat type and GraphicRepresentationStatus enum to reflect the latest Mesh Export Service docs. These are breaking changes to beta APIs intended to go into iTwin.js 5.0.

[eringram]

@danieliborra @arvindsvenkat To clarify, is "3DFT" as an export type still returned by the service? If so I'll add it here

[markschlosseratbentley]

Looks good to me.
I will defer to @danieliborra and @arvindsvenkat for final approval, though.
Do we need to notify anyone of this change?

[aruniverse]

will this be needed in 4.10 or 4.11?

[aruniverse]

why is the cast here necessary?

[eringram]

Without the cast the compiler was complaining about the type of format being incorrect, inferred to be string instead of GraphicRepresentationFormat. Explicitly stating the type is wordier but is that preferred? E.g.

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: {
    iTwinId: "iTwinId",
    id: "srcId",
    changeId: undefined,
    type: "srcType",
  },
  format: "IMODEL",
};

[aruniverse]

while wordier, i think its safer to extract the type out for an internal interface to use

[eringram]

Fixed

[aruniverse]

curious why in one place we're using a string literal type and another place an enum

[eringram]

I don't completely remember, but my guess is because GraphicRepresentationFormat used to have enum values that were strings different from the constant names, like this:

export enum GraphicRepresentationStatus {
  InProgress = "In progress",
  Complete = "Complete",
  NotStarted = "Not started",
  Failed = "Failed"
}

Why those different strings were necessary to begin with, I'm not sure and it could have just been a poor decision. Since all that is needed are the strings "InProgress", "Complete", "NotStarted", and "Invalid", it could become a type like GraphicRepresentationFormat

[eringram]

I realized one reason we did this is the enum is used in a conditional type definition of GraphicRepresentation here:

export type GraphicRepresentation = {
  displayName: string;
  representationId: string;
  status: GraphicRepresentationStatus;
  format: GraphicRepresentationFormat;
  dataSource: DataSource;
  /** The url of the graphic representation
   * @note The url can only be guaranteed to be valid if the status is complete.
   * Therefore, the url is optional if the status is not complete, and required if the status is complete.
   */
} & ({
  status: Omit<GraphicRepresentationStatus, GraphicRepresentationStatus.Complete>;
  url?: string;
} | {
  status: GraphicRepresentationStatus.Complete;
  url: string;
});

Where the url prop is only guaranteed to exist if status = GraphicRepresentationStatus.Complete. This could also be done with a union type though with Exclude<GraphicRepresentationStatus, "Complete">, etc. instead of Omit.

[eringram]

@aruniverse do you have a preference between enum and string literal type here?

[aruniverse]

I personally would prefer the string literals, not a huge fan of enums. I think the Exclude utility would be perfect for the discriminated union type

[eringram]

Also fixed this

[eringram]

@aruniverse will this be needed in 4.10 or 4.11?

No, we were planning for it to go in 5.0.

[eringram]

Updated the GraphicRepresentationFormat type to be a union of strings, which unfortunately requires this long if statement to enforce that url has type string only if status === "Complete", and type string | undefined otherwise. I tried to do this with a ternary operator but that doesn't work so I think this is the best solution to avoid more type assertions.