Add status_url & status_events. (#431)

* Add status_url & status_events.

Add externalDocs, tag metadata, and info in spec.

* spelling fix in `ChargeDetails` tsp model

* grammar fix in `paramsDescription` in requests.tsp

* spec updates

---------

Co-authored-by: hey-august <[email protected]>

Author: Devon-White

specs/signalwire-rest/calling-api/calls/const.tsp

@@ -0,0 +1 @@
+import "../../_globally_shared/const.tsp";

specs/signalwire-rest/calling-api/calls/main.tsp

@@ -21,7 +21,8 @@ namespace CallingAPI.Calls {
         }
       | StatusCode401
       | StatusCode404
-      | CallCreate422Error;
+      | CallCreate422Error
+      | StatusCode500;
 
     @summary("Update a Call")
     @doc("To update an existing call, you send a `PUT` request to the Call resource with a payload including a `command` and additional nested `params`.")
@@ -55,6 +56,7 @@ namespace CallingAPI.Calls {
         }
       | StatusCode401
       | StatusCode404
-      | CallUpdate422Error;
+      | CallUpdate422Error
+      | StatusCode500;
   }
 }

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

@@ -1,14 +1,16 @@
+import "../const.tsp";
+
 model Call {
   @doc("The unique identifier of the call on SignalWire. This can be used to update the call programmatically.")
-  @example("3fa85f64-5717-4562-b3fc-2c963f66afa6")
+  @example("0e9c80d7-a149-4917-892d-420043709f45")
   id: string;
 
   @doc("The origin number or address.")
-  @example("sip:[email protected]")
+  @example("+12069708643")
   from: string;
 
   @doc("The destination number or address.")
-  @example("sip:[email protected]")
+  @example("+18048390497")
   to: string;
 
   @doc("The direction of the call.")
@@ -20,33 +22,51 @@ model Call {
   status: "answered" | "queued" | "initiated" | "ringing" | "ending" | "ended";
 
   @doc("The duration of the call in seconds.")
-  @example(60)
-  duration: integer;
+  @example(null)
+  duration: integer | null;
 
   @doc("The duration of the call in milliseconds.")
-  @example(60000)
-  duration_ms: integer;
+  @example(null)
+  duration_ms: integer | null;
 
-  @doc("The billable duration of the call in seconds.")
-  @example(60)
-  billable_duration: integer;
+  @doc("The billable duration of the call in milliseconds.")
+  @example(null)
+  billing_ms: integer | null;
 
   @doc("Source of this call.")
   @example("realtime_api")
   source: "realtime_api";
 
   @doc("Type of this call.")
-  @example("relay_sip_call")
+  @example("relay_pstn_call")
   type: "relay_pstn_call" | "relay_sip_call" | "relay_webrtc_call";
 
+  @doc("The URL associated with this call.")
+  @example(null)
+  url: string | null;
+
+  @doc("Total charge for this call.")
+  @example(0)
+  charge: float64;
+
+  @doc("The date and time when the call was created.")
+  @example(UTC_TIME_EXAMPLE)
+  created_at: utcDateTime;
+
+  @doc("The parent call ID if this is a child call.")
+  @example(null)
+  parent_id: string | null;
+
   @doc("Details on charges associated with this call.")
-  charge: ChargeDetails[];
+  charge_details: ChargeDetails[];
 }
 
 model ChargeDetails {
   @doc("Description for this charge.")
+  @example("Text to Speech")
   description: string;
 
   @doc("Charged amount.")
-  amount: integer;
+  @example(0.121176)
+  amount: float;
 }

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

@@ -16,7 +16,7 @@ const updateCommandDescription = "The `update` command is used to update a exist
 
 const uuidDescription = "The unique identifying ID of a existing call.";
 
-const paramsDescription = "An object of parameters to that will be utilized by the active command.";
+const paramsDescription = "An object of parameters that will be utilized by the active command.";
 
 alias CallCreateRequestAlias = CallCreateParamsURL | CallCreateParamsSWML;
 
@@ -120,6 +120,20 @@ model CallCreateParamsBase {
   @doc("The Fallback URL to handle the call. This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call.")
   @example(CallFallbackURLExample)
   fallback_url?: string;
+
+  @doc("A URL that will recieve status updates of the current call. Any call events defined in `status_events` will be delivered to the defined URL.")
+  @example("https://example.com/status_callback")
+  status_url?: url;
+
+  @doc("The call events that will be monitored and sent to the `status_url` when active.")
+  @example(#["answered", "ended"])
+  status_events?: (
+    | "answered"
+    | "queued"
+    | "initiated"
+    | "ringing"
+    | "ending"
+    | "ended")[];
 }
 
 @summary("Create call (URL)")

specs/signalwire-rest/calling-api/main.tsp

@@ -1,21 +1,36 @@
 import "@typespec/http";
+import "@typespec/openapi";
 import "../types";
 import "./calls";
+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",
+  "The Calling API holds a collection of endpoints that will help you create and manage calls."
+)
+@info(#{
+  title: "Calling API",
+  version: "1.0.0",
+  contact: CONTACT_INFO,
+  license: LICENSE_INFO,
+  termsOfService: TERMS_OF_SERVICE,
+})
 @service(#{ title: "Calling API" })
 @server(
-  "https://{space_name}.signalwire.com/api/calling",
+  "https://{space_name}.${SERVER_URL}/calling",
   "Endpoint",
   {
+    @doc(SERVER_URL_DESCRIPTION)
+    @example("example")
     space_name: string = "{Your_Space_Name}",
   }
 )
 @useAuth(BasicAuth)
-@doc("""
-  API to create/manage SignalWire's Calls.
-  To create a new Call, you send a `POST` request to the Call resource with a payload including a `dial` command and additional nested `params`.
-  """)
+@doc("API to create/manage SignalWire's Calls.")
 namespace CallingAPI;

specs/signalwire-rest/calling-api/tags.tsp

@@ -0,0 +1,11 @@
+import "@typespec/openapi3";
+
+const CALLS_TAG = "Calls";
+
+const CALLS_TAG_METADATA = #{
+  description: "Endpoints related to creating and managing calls",
+  externalDocs: #{
+    url: "https://developer.signalwire.com/rest/signalwire-rest/endpoints/calling/calls",
+    description: "Developer documentation on Calling API Call endpoints",
+  },
+};