@microsoft/typespec-msgraph 0.0.1-Preview.13 → 0.0.1-Preview.14

package/lib/decorators.tsp

@@ -16,14 +16,31 @@ extern dec action(target: Operation, name?: valueof string);
 
 /**
  * `@additionalQueryParameters` - Appends a key=value pair to the query string of the mapped internal URL for all models defined within the namespace.
- * 
+ *
  * `@additionalQueryParameters` can only be applied to namespaces
  */
-extern dec additionalQueryParameters(target: Namespace, name: valueof string, value: valueof string);
+extern dec additionalQueryParameters(
+  target: Namespace,
+  name: valueof string,
+  value: valueof string
+);
+
+/**
+ * `@addressUrl` - Specifies the URL to which the operation request is forwarded when the request
+ * is authenticated with an AAD account.
+ *
+ * `@addressUrl` can only be applied to routed interfaces (entity sets, singletons and navigation properties) or action operations.
+ */
+extern dec addressUrl(
+  target: Interface | Operation,
+  url: valueof string,
+  omitRootNavigationSegment?: valueof boolean,
+  appendSegmentNameToAddress?: valueof boolean
+);
 
 /**
  * `@agsAttribute` - Allows all AGS CSDL extensions that are not yet modelled explicitly in TypeSpec to be maintained
- * 
+ *
  * `@agsAttribute` - Applies to models.
  */
 extern dec agsAttribute(
@@ -34,10 +51,10 @@ extern dec agsAttribute(
 
 /**
  * `@allowedValues` - mark model property with allowedValues.
- * 
+ *
  * `@allowedValues` - can only be applied to model properties.
  */
- extern dec allowedValues(target: ModelProperty, ...values: valueof unknown[]);
+extern dec allowedValues(target: ModelProperty, ...values: valueof unknown[]);
 
 /**
  * `@alternateKey` - mark a model property as an alternateKey
@@ -86,7 +103,17 @@ extern dec deltaCollection(target: Model);
  *
  * `@graphDeprecated` can be applied to Model, ModelProperty, Enum, EnumMember, Operation, Namespace, Interface.
  */
- extern dec graphDeprecated(target: Model | ModelProperty | Enum | EnumMember | Operation | Namespace | Interface, name: valueof string);
+extern dec graphDeprecated(
+  target:
+    | Model
+    | ModelProperty
+    | Enum
+    | EnumMember
+    | Operation
+    | Namespace
+    | Interface,
+  name: valueof string
+);
 
 /**
  * `@deprecatedDefinition` - Allow us create a reusable deprecation definition.
@@ -115,14 +142,27 @@ extern dec entity(target: Model);
  * `properties` - Property names in the model returned from the get that can be used in a $expand query parameter.
  * At least one property must be specified.
  */
-extern dec expand(target: Operation, property: valueof string, ...otherProperties: valueof string[]);
+extern dec expand(
+  target: Operation,
+  property: valueof string,
+  ...otherProperties: valueof string[]
+);
 
 /**
  * `@experimental` - mark the entity as experimental
  *
  * `@experimental` can be applied to Model, ModelProperty, Enum, EnumMember, Operation, Namespace, Interface.
  */
-extern dec experimental(target: Model | ModelProperty | Enum | EnumMember | Operation | Namespace | Interface);
+extern dec experimental(
+  target:
+    | Model
+    | ModelProperty
+    | Enum
+    | EnumMember
+    | Operation
+    | Namespace
+    | Interface
+);
 
 /**
  * `@filter` - Applies to: get operations that return collections of @entity or @complex models.
@@ -131,8 +171,11 @@ extern dec experimental(target: Model | ModelProperty | Enum | EnumMember | Oper
  * `properties` - array of property names in the model returned
  * from the get operation that can be used in $filter query parameter.
  */
-extern dec filter(target: Operation, property: valueof string, ...properties: valueof string[]);
-
+extern dec filter(
+  target: Operation,
+  property: valueof string,
+  ...properties: valueof string[]
+);
 
 /**
  * `@flags` - mark an enumeration type as a flag.
@@ -153,18 +196,20 @@ extern dec function(target: Operation, name?: valueof string);
  *
  * `@globalOperation` can only be applied to operations.
  */
- extern dec globalOperation(target: Operation);
-
+extern dec globalOperation(target: Operation);
 
 /**
  * `@graphRoute` - mark an interface or operation with an HTTP route.
- * 
+ *
  * `@graphRoute` - can only be applied to interfaces or operations.
  */
 // TODO: Using @graphRoute on an operation currently does not work due to the following TypeSpec core issue
 // https://github.com/microsoft/typespec/issues/2106
 // Disabling all related features while we await the outcome.
-extern dec graphRoute(target: Interface /* | Operation */, path: valueof string);
+extern dec graphRoute(
+  target: Interface,  /* | Operation */
+  path: valueof string
+);
 
 /**
  * `@hasStream` - indicates that an `@entity` model has a stream.
@@ -185,7 +230,7 @@ extern dec immutable(target: ModelProperty);
  *
  * `@ownerless` can only be applied to interfaces.
  */
- extern dec ownerless(target: Interface);
+extern dec ownerless(target: Interface);
 
 /**
  * `@open` - mark a model type as open
@@ -210,7 +255,11 @@ extern dec operationParameters(target: Model);
  * `properties` - List of property names in the model returned from the get operation that can be used in a $orderBy query parameter.
  * At least one property must be specified.
  */
-extern dec orderBy(target: Operation, property: valueof string, ...otherProperties: valueof string[]);
+extern dec orderBy(
+  target: Operation,
+  property: valueof string,
+  ...otherProperties: valueof string[]
+);
 
 /**
  * `@pagedCollection` - mark a model as representing a paged collection.
@@ -252,7 +301,9 @@ extern dec privatePreviewDefinition(
  *
  * `@privileged` can be applied to Model, ModelProperty, Enum, EnumMember, Operation, Namespace.
  */
-extern dec privileged(target: Model | ModelProperty | Enum | EnumMember | Operation | Namespace);
+extern dec privileged(
+  target: Model | ModelProperty | Enum | EnumMember | Operation | Namespace
+);
 
 /**
  * `@publicNamespace` - defines the namespace to be used in generating CSDL output for all elements contained within the namespace
@@ -275,6 +326,13 @@ extern dec readOnly(target: ModelProperty);
  */
 extern dec references(target: ModelProperty);
 
+/**
+ * `@referenceTarget` - mark an interface with referenceTarget
+ *
+ * `@references` can only be applied to interfaces.
+ */
+ extern dec referenceTarget(target: Interface, value: valueof string);
+
 /**
  * `@requiredForCreate` - mark a model property as required when a request is made to
  * Graph to create or update a resource.
@@ -295,11 +353,22 @@ extern dec search(target: Operation);
  */
 extern dec skip(target: Operation);
 
+/**
+ * `@select` - Applies to operations
+ *  Indicates that the operation supports the OData $select query parameter
+ */
+ extern dec select(target: Operation);
+
 /**
  * `@term` - Applies to: namespaces.
  * Indicates that a workload wishes to require or return instance annotations in their request / response packets at runtime.
  */
-extern dec term(target: Namespace, name: valueof string, type: Scalar, description: valueof string);
+extern dec term(
+  target: Namespace,
+  name: valueof string,
+  type: Scalar,
+  description: valueof string
+);
 
 /**
  * `@top` - Applies to: get operations that return collections.
@@ -315,10 +384,10 @@ extern dec top(target: Operation);
 extern dec writeOnly(target: ModelProperty);
 
 /**
-* `@isOwner` - specify that this workload is the primary owner of this entity model
-*
-* `@isOwner` can be applied to Model where the model also has an @entity decorator or a ModelProperty where it has either an @contains or @references decorator.
-*/
+ * `@isOwner` - specify that this workload is the primary owner of this entity model
+ *
+ * `@isOwner` can be applied to Model where the model also has an @entity decorator or a ModelProperty where it has either an @contains or @references decorator.
+ */
 extern dec isOwner(target: Model | ModelProperty, value?: valueof boolean);
 
 /**

package/lib/porcelain.tsp

@@ -41,8 +41,6 @@ namespace MsGraph;
   @doc("Primary operation shapes for Microsoft Graph")
   interface GraphOps {
 
-    // TODO: This is how we should make $select standard for Graph.  Define a select decorator and use it here.
-    // @select("*") 
     @get op GetCollection<
     TResource extends {} = Automatic.CalculatedResourceType,
     TParams =  {... Automatic.GraphRouteParams},
@@ -51,7 +49,6 @@ namespace MsGraph;
     > is Foundations.GraphFoundations.CollectionOperation<
       TResource, TParams, TResponse, TErrorResponse>;
 
-    // @select("*")
     @get op GetPagedCollection<
     TResource extends {} = Automatic.CalculatedResourceType,
     TParams =  {... Automatic.GraphRouteParams},
@@ -62,7 +59,6 @@ namespace MsGraph;
 
 // TODO: GetDelta?  FUnction etc.?
 
-    // @select("*")
     @post op Post<
       TResource extends {} = Automatic.CalculatedResourceType,
       TParams = { ... Automatic.GraphRouteParams, @body body: TResource },
@@ -71,7 +67,6 @@ namespace MsGraph;
     > is Foundations.GraphFoundations.CollectionOperation<
       TResource, TParams, TResponse, TErrorResponse>;
         
-    // @select("*")
     @get op GetResource<
     TResource extends {} = Automatic.CalculatedResourceType,
     TParams =  {... Automatic.GraphRouteParams},
@@ -96,7 +91,6 @@ namespace MsGraph;
     > is Foundations.GraphFoundations.ResourceOperation<
       TResource, TParams, TResponse, TErrorResponse>;
 
-    // @select("*")
     @patch op PatchWithResponse<
     TResource extends {} = Automatic.CalculatedResourceType,
     TParams =  {... Automatic.GraphRouteParams},
@@ -113,7 +107,6 @@ namespace MsGraph;
     > is Foundations.GraphFoundations.ResourceOperation<
       TResource, TParams, TResponse, TErrorResponse>;
 
-    // @select("*")
     @put op PutWithResponse<
     TResource extends {} = Automatic.CalculatedResourceType,
     TParams =  {... Automatic.GraphRouteParams},
@@ -122,6 +115,24 @@ namespace MsGraph;
     > is Foundations.GraphFoundations.ResourceOperation<
       TResource, TParams, TResponse, TErrorResponse>;
 
+    @action op Action<
+    TReturnType = void,
+    TActionParams extends {} = {},
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams, ... TActionParams},
+    TResponse = TReturnType,
+    TErrorResponse = MsGraph.Responses.OperationErrorResponse
+    >(...TParams): TResponse | TErrorResponse;
+
+    @function op Function<
+    TReturnType,
+    TFunctionParams extends {} = {},
+    TResource extends {} = Automatic.CalculatedResourceType,
+    TParams =  {... Automatic.GraphRouteParams, ... TFunctionParams},
+    TResponse = TReturnType,
+    TErrorResponse = MsGraph.Responses.OperationErrorResponse
+    >(...TParams): TResponse | TErrorResponse;
+
   }
 
   namespace Automatic {

package/lib/responses.tsp

@@ -16,9 +16,27 @@ using MsGraph.SharedModels;
 // The content of the types exists for other future emitters that run directly off TypeSpec.
 namespace MsGraph.Responses.Bodies {
 
+  /** Complex type to represent a nested error that potentially has other recursive nested errors. */
+  @error
+  model InnerError {
+    code: string;
+    innererror: InnerError | null; // Small e for error NOT a typo.
+  }
+
+  /** Complex type to represent a standard Microsoft Graph error. */
+  @error
+  model GraphError {
+    code: string;
+    message: string;
+    localizedMessage: string;
+    target: string | null;
+    innererror: InnerError | null;  // Small e for error NOT a typo.
+    details: GraphError[];
+  }
+
   @error
   model ErrorBody {
-    error: publicError;
+    error: GraphError;
   }
 
   model ResourceBody<TResource> {
@@ -44,33 +62,39 @@ namespace MsGraph.Responses.Bodies {
 
 // Response models represent the response as a whole, including the status code, headers, and body.
 namespace MsGraph.Responses {
-  @doc("Response to represent a Microsoft Graph collection response payload.")
+  /** Response to represent a Microsoft Graph collection response payload. */
   model CollectionResponse<TResource, TStatus = 200, TBody = Bodies.CollectionBody<TResource>> 
     is Http.Response<TStatus> {
     ...Http.Body<TBody>;
   }
 
-  @doc("Response to represent a Microsoft Graph paged collection response payload.")
+  /** Response to represent a Microsoft Graph paged collection response payload. */ 
   model PagedCollectionResponse<TResource, TStatus = 200, TBody = Bodies.PagedCollectionBody<TResource>>
     is CollectionResponse<TResource, TStatus, TBody>;
 
-  @doc("Response to represent a Microsoft Graph individual resource response payload.")
+  /** Response to represent a Microsoft Graph individual resource response payload. */
   model ResourceResponse<TResource, TStatus = 200, TBody = Bodies.ResourceBody<TResource>>
     is Http.Response<TStatus> {
     ...Http.Body<TBody>;
   }
 
-  @doc("Response to represent a Microsoft Graph resource creation response payload.")
+  /** Response to represent a Microsoft Graph individual resource response payload. */
+  model ScalarResponse<TScalar, TStatus = 200, TBody = TScalar>
+    is Http.Response<TStatus> {
+    ...Http.Body<TBody>;
+  }
+
+  /** Response to represent a Microsoft Graph resource creation response payload. */
   model ResourceCreatedResponse<TResource, TStatus = 201, TBody = Bodies.ResourceBody<TResource>>
     is ResourceResponse<TResource, TStatus, TBody> {
     ...Http.LocationHeader
   }
 
-  @doc("Response to represent a Microsoft Graph empty response payload.")
+  /** Response to represent a Microsoft Graph empty response payload. */
   model EmptyResponse
     is Http.Response<204>;
   
-  @doc("Response to represent a Microsoft Graph error response payload.")
+  /** Response to represent a Microsoft Graph error response payload. */
   model ErrorResponse<TStatus>
    is Http.Response<TStatus> {
     ...Http.Body<Bodies.ErrorBody>;
@@ -78,5 +102,6 @@ namespace MsGraph.Responses {
 
   alias ResourceErrorResponse = ErrorResponse<400 | 404 | 429>;
   alias CollectionErrorResponse = ErrorResponse<400 | 429>;
+  alias OperationErrorResponse = ErrorResponse<400 | 429>;
   
 }

package/lib/shared-models.tsp

@@ -16,35 +16,6 @@ namespace MsGraph.SharedModels;
     @key id: string;
   }
 
-  @doc("Complex type to represent an identity principal by id, when a human-readable name is also useful.")
-  @complex
-  @open
-  model identity {
-    id: string;
-    displayName: string;
-  }
-
-  @doc("Complex type to represent a group of identity principals used at a point in time, such as createdBy, lastModifiedBy.")
-  @complex
-  @open
-  model identitySet {
-    user: identity | null;
-    device: identity | null;
-    application: identity | null;
-  }
-
-  @doc("Enum for identifying the format of a text string.")
-  enum bodyType {
-    text,
-    html
-  }
-
-  @doc("Complex type to represent a chunk of text that could be either plain text or html.")
-  @complex
-  model itemBody {
-    contentType: bodyType;
-    content: string;
-  }
 
   @doc("Scalar type for URLs that would be expected to work in the browser address bar.")
   scalar webUrl extends string;
@@ -52,24 +23,3 @@ namespace MsGraph.SharedModels;
   @doc("Scalar type for URLs that represent Graph APIs.")
   scalar url extends string;
 
-  @doc("Complex type to represent a nested error that potentially has other recursive nested errors.")
-  @complex
-  @open
-  model innerError {
-    code: string;
-    innererror: innerError | null;
-  }
-
-  @doc("""
-  Complex type to represent a standard Microsoft Graph error.
-  {code}: The error code.
-  """)
-  @complex
-  @error
-  model publicError {
-    code: string;
-    message: string;
-    target: string | null;
-    innererror: innerError | null;
-    details: publicError[];
-  }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/typespec-msgraph",
-  "version": "0.0.1-Preview.13",
+  "version": "0.0.1-Preview.14",
   "author": "Microsoft Corporation",
   "description": "TypeSpec for Microsoft Graph provides a description of the Microsoft Graph APIs. It is used for generating API description languages, client and service code, documentation, and other assets.",
   "homepage": "https://github.com/microsoftgraph/typespec-msgraph",
@@ -53,8 +53,8 @@
   ],
   "dependencies": {
     "@xmldom/xmldom": "~0.8.4",
-    "@typespec/compiler": "~0.51.0",
-    "@typespec/http": "~0.51.0",
+    "@typespec/compiler": "~0.52.0",
+    "@typespec/http": "~0.52.0",
     "prettier": "~3.1.1",
     "react-dom": "~18.2.0",
     "react": "~18.2.0",
@@ -65,7 +65,7 @@
     "@types/node": "~18.11.9",
     "@types/react": "~18.0.5",
     "@types/react-reconciler": "~0.28.0",
-    "@typespec/eslint-config-typespec": "~0.51.0",
+    "@typespec/eslint-config-typespec": "~0.52.0",
     "c8": "~8.0.1",
     "eslint": "^8.49.0",
     "mocha": "~10.2.0",