Update Calling API specs to reflect OpenRPC better

specs/package.json

@@ -5,10 +5,11 @@
   "scripts": {
     "build": "yarn build:api",
     "build:all": "yarn build:api && yarn build:schema",
-    "build:api": "yarn build:calling-api && yarn build:chat-api && yarn build:datasphere-api && yarn build:fabric-api && yarn build:logs-api && yarn build:fax-api && yarn build:message-api && yarn build:voice-api && yarn build:pubsub-api",
+    "build:api": "yarn build:calling-api && yarn build:calling-api-docs && yarn build:chat-api && yarn build:datasphere-api && yarn build:fabric-api && yarn build:logs-api && yarn build:fax-api && yarn build:message-api && yarn build:voice-api && yarn build:pubsub-api",
     "build:schema": "yarn build:swml",
     "build:swml": "cd ./swml && tsp compile . && cd ../",
     "build:calling-api": "cd ./signalwire-rest/calling-api && tsp compile . && cd ../../",
+    "build:calling-api-docs": "cd ./signalwire-rest/calling-api/open-rpc/dial && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/update && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/calling-end && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/calling-ai-hold && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/calling-ai-unhold && tsp compile . && cd ../../../../ && cd ./signalwire-rest/calling-api/open-rpc/calling-ai-message && tsp compile . && cd ../../../../",
     "build:chat-api": "cd ./signalwire-rest/chat-api && tsp compile . && cd ../../",
     "build:datasphere-api": "cd ./signalwire-rest/datasphere-api && tsp compile . && cd ../../",
     "build:fabric-api": "cd ./signalwire-rest/fabric-api && tsp compile . && cd ../../",

specs/signalwire-rest/calling-api/calls/models/requests.tsp

@@ -18,7 +18,9 @@ const uuidDescription = "The unique identifying ID of a existing call.";
 
 const paramsDescription = "An object of parameters that will be utilized by the active command.";
 
-alias CallCreateRequestAlias = CallCreateParamsURL | CallCreateParamsSWML;
+alias CallCreateParamsAlias = CallCreateParamsURL | CallCreateParamsSWML;
+
+alias CallUpdateParamsAlias = CallUpdateParamsURL | CallUpdateParamsSWML;
 
 @summary("Hangup call")
 model CallHangupRequest {
@@ -101,7 +103,7 @@ model CallCreateRequest {
   command: "dial";
 
   @doc(paramsDescription)
-  params: CallCreateRequestAlias;
+  params: CallCreateParamsAlias;
 }
 
 model CallCreateParamsBase {
@@ -189,34 +191,19 @@ model CallUpdateParamsURL is CallUpdateParamsBase {
 }
 
 @summary("Update call")
-@oneOf
-union UpdateCurrentCallRequest {
-  CallUpdateSWMLRequest,
-  CallUpdateURLRequest,
-}
-
-union CallUpdateRequest {
-  UpdateCurrentCallRequest,
-  CallHangupRequest,
-  CallHoldRequest,
-  CallUnholdRequest,
-  CallAIMessageRequest,
-}
-
-model CallUpdateRequestBase {
+model CallUpdateCurrentCallRequest {
   @doc(updateCommandDescription)
   @example("update")
   command: "update";
-}
 
-@summary("Update call (SWML)")
-model CallUpdateSWMLRequest is CallUpdateRequestBase {
   @doc(paramsDescription)
-  params: CallUpdateParamsSWML;
+  params: CallUpdateParamsAlias;
 }
 
-@summary("Update call (URL)")
-model CallUpdateURLRequest is CallUpdateRequestBase {
-  @doc(paramsDescription)
-  params: CallUpdateParamsURL;
+union CallUpdateRequest {
+  CallUpdateCurrentCallRequest,
+  CallHangupRequest,
+  CallHoldRequest,
+  CallUnholdRequest,
+  CallAIMessageRequest,
 }

specs/signalwire-rest/calling-api/open-rpc/calling-ai-hold/main.tsp

@@ -0,0 +1,55 @@
+import "@typespec/http";
+import "@typespec/openapi";
+import "../../../types";
+import "../../calls/models/requests.tsp";
+import "../../calls/models/responses.tsp";
+import "../../../_globally_shared/const.tsp";
+import "../../tags.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+using Types.StatusCodes;
+
+@tagMetadata(CALLS_TAG, CALLS_TAG_METADATA)
+@externalDocs(
+  "https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls/calling-ai-hold",
+  "Documentation for the calling.ai_hold command to hold AI calls."
+)
+@info(#{
+  title: "Calling API - Calling AI Hold",
+  version: "1.0.0",
+  contact: CONTACT_INFO,
+  license: LICENSE_INFO,
+  termsOfService: TERMS_OF_SERVICE,
+})
+@service(#{ title: "Calling API - Calling AI Hold" })
+@server(
+  "https://{space_name}.${SERVER_URL}/calling",
+  "Endpoint",
+  {
+    @doc(SERVER_URL_DESCRIPTION)
+    @example("example")
+    space_name: string = "{Your_Space_Name}",
+  }
+)
+@useAuth(BasicAuth)
+@doc("API to hold AI SignalWire calls using the calling.ai_hold command.")
+namespace CallingAPI.AIHold;
+
+@route("/calls")
+@tag("Calls")
+interface AIHoldCommand {
+  @summary("Hold an AI Call")
+  @doc("To hold an existing AI call, you send a `POST` request to the Call resource with a payload including a `calling.ai_hold` command and the call ID. This pauses the AI conversation.")
+  @operationId("hold-ai")
+  @post
+  hold(@body request: CallHoldRequest):
+    | {
+        @statusCode statusCode: 200;
+        @body call: CallResponse;
+      }
+    | StatusCode401
+    | StatusCode404
+    | CallUpdate422Error
+    | StatusCode500;
+}