Convert Fabric APIs to TypeSpec (#373)

* Initial push

* Convert all Fabric api spec to TypeSpec

* add newline

* Update main.tsp

* Update responses.tsp

* Update main.tsp

* Update core.tsp

* Update errors.tsp

* Update requests.tsp

* Push audit edits (in-progress)

* Update specs/signalwire-rest/fabric-api/dialogflow-agents/addresses/models/core.tsp

Co-authored-by: Cassie <[email protected]>

* Add enums for Ciphers, Codecs, and Encryption in globally_shared specs

- Introduced Ciphers enum with various AES cipher options.
- Added Codecs enum for audio and video codecs including PCMU, PCMA, G722, G729, OPUS, VP8, and H264.
- Created Encryption enum to define encryption requirements: Required, Optional, and Default.

* edits

* edits

* edits

* edits

* edits

* Add global constants and SIP endpoint enums

- Introduced a new constant for the server URL in const.tsp.
- Added an enumeration for CallHandlerType in enums.tsp, defining various call handling options.

- Add pagination response for many list endpoints

* Refactor API tags and documentation for SignalWire Fabric API

- Introduced a new tags.tsp file to centralize tag definitions and metadata for various API endpoints.
- Updated multiple API specifications to replace hardcoded tag strings with constants from the new tags.tsp file.
- Enhanced OpenAPI documentation by adding summaries and descriptions for various endpoints, improving clarity and usability.
- Added external documentation links for each tag to facilitate developer access to relevant resources.
- Ensured consistent naming conventions across all API tags to improve readability and maintainability.

* Fix bad summary

* Conference Room edits

* add missing fps property to conference rooms

* Add redirects

* Add status callback fields to CXML and SWML Scripts endpoints (#387)

* Add status callback fields to CXML and SWML Scripts endpoints

* Update core.tsp

* Update specs/signalwire-rest/fabric-api/cxml-scripts/models/requests.tsp

* Update specs/signalwire-rest/fabric-api/cxml-scripts/models/requests.tsp

* Update specs/signalwire-rest/fabric-api/swml-scripts/models/requests.tsp

* Update specs/signalwire-rest/fabric-api/swml-scripts/models/requests.tsp

---------

Co-authored-by: Devon <[email protected]>

* recompile spec after additions

* Update specs/signalwire-rest/fabric-api/cxml-applications/models/requests.tsp

Co-authored-by: Cassie <[email protected]>

* Update specs/signalwire-rest/fabric-api/cxml-applications/models/core.tsp

Co-authored-by: Cassie <[email protected]>

* Update specs/signalwire-rest/fabric-api/cxml-applications/models/core.tsp

Co-authored-by: Cassie <[email protected]>

* Update specs/signalwire-rest/fabric-api/cxml-applications/models/requests.tsp

Co-authored-by: Cassie <[email protected]>

* Update specs/signalwire-rest/fabric-api/cxml-applications/models/requests.tsp

Co-authored-by: Cassie <[email protected]>

* Update specs/signalwire-rest/fabric-api/cxml-applications/models/responses.tsp

Co-authored-by: Cassie <[email protected]>

* Update specs/signalwire-rest/fabric-api/cxml-applications/models/responses.tsp

Co-authored-by: Cassie <[email protected]>

* Ran TypeSpec formatter

* Ran formatter, and recompiled spec

---------

Co-authored-by: Cassie <[email protected]>
Co-authored-by: diego-signalwire <[email protected]>

Author: 3 people

.cursor/rules/openapi-comparison-prompt.md

@@ -9,6 +9,7 @@
   ],
   "scripts": {
     "build": "yarn --cwd website build",
+    "serve": "yarn --cwd website serve",
     "start": "yarn --cwd website start",
     "start-fresh": "yarn --cwd website start-fresh",
     "build:website": "yarn --cwd website build",

.cursor/rules/typespec.md

@@ -10,14 +10,16 @@
     "build:fabric-api": "cd ./signalwire-rest/fabric-api && tsp compile . && cd ../../",
     "build:logs-api": "cd ./signalwire-rest/logs-api && tsp compile . && cd ../../",
     "clean": "echo 'Skipping clean step'",
-    "prebuild": "yarn clean"
+    "prebuild": "yarn clean",
+    "format": "tsp format **/*.tsp",
+    "format:check": "tsp format --check **/*.tsp"
   },
   "dependencies": {
-    "@typespec/compiler": "1.0.0",
-    "@typespec/http": "1.0.0",
-    "@typespec/openapi": "1.0.0",
-    "@typespec/openapi3": "1.0.0",
-    "@typespec/rest": "0.70.0"
+    "@typespec/compiler": "1.1.0",
+    "@typespec/http": "1.1.0",
+    "@typespec/openapi": "1.1.0",
+    "@typespec/openapi3": "1.1.0",
+    "@typespec/rest": "0.71.0"
   },
   "devDependencies": {
     "typescript": "^5.5.4"

package.json

@@ -0,0 +1,21 @@
+const SERVER_URL = "signalwire.com/api";
+
+const TERMS_OF_SERVICE = "https://signalwire.com/legal/signalwire-cloud-agreement";
+
+const CONTACT_NAME = "SignalWire";
+
+const CONTACT_URL = "https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011";
+
+const CONTACT_EMAIL = "[email protected]";
+
+const LICENSE_URL = "https://github.com/signalwire/docs/blob/main/LICENSE";
+
+const LICENSE_NAME = "MIT";
+
+const CONTACT_INFO = #{
+  name: CONTACT_NAME,
+  url: CONTACT_URL,
+  email: CONTACT_EMAIL,
+};
+
+const LICENSE_INFO = #{ name: LICENSE_NAME, url: LICENSE_URL };

specs/package.json

@@ -0,0 +1,23 @@
+enum Ciphers {
+  AEAD_AES_256_GCM_8: "AEAD_AES_256_GCM_8",
+  AES_256_CM_HMAC_SHA1_80: "AES_256_CM_HMAC_SHA1_80",
+  AES_CM_128_HMAC_SHA1_80: "AES_CM_128_HMAC_SHA1_80",
+  AES_256_CM_HMAC_SHA1_32: "AES_256_CM_HMAC_SHA1_32",
+  AES_CM_128_HMAC_SHA1_32: "AES_CM_128_HMAC_SHA1_32",
+}
+
+enum Codecs {
+  PCMU: "PCMU",
+  PCMA: "PCMA",
+  G722: "G722",
+  G729: "G729",
+  OPUS: "OPUS",
+  VP8: "VP8",
+  H264: "H264",
+}
+
+enum Encryption {
+  Required: "required",
+  Optional: "optional",
+  Default: "default",
+}

specs/signalwire-rest/_globally_shared/const.tsp

@@ -4,40 +4,57 @@ import "./models/requests.tsp";
 import "./models/responses.tsp";
 import "./models/examples.tsp";
 
-
 using TypeSpec.Http;
 using Types.StatusCodes;
 
 @route("/calls")
 namespace CallingAPI.Calls {
-    
-    @tag("Calls")
-    @friendlyName("Calls")
-    interface Calls {
-
-        @summary("Create a Call")
-        @doc("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`.")
-        create(@body request: CallCreateRequest):
-        { @statusCode statusCode: 201; @body call: CallResponse; } |
-        StatusCode401 |
-        StatusCode404 |
-        CallCreate422Error;
-
-
-        @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`.")
-        @opExample(#{parameters: holdCallExample}, #{title: "Hold active call", description: "Put an active AI call on hold, pausing the conversation"})
-        @opExample(#{parameters: unholdCallExample}, #{title: "Unhold active call", description: "Resume an AI call that was previously put on hold"})
-        @opExample(#{parameters: aiMessageExample}, #{title: "Inject AI message", description: "Send a message to the AI conversation to modify behavior or add context"})
-        //@opExample(#{parameters: #{request: #{command: "update", params: #{id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", url: "https://example.com/swml", fallback_url: "https://example.com/fallback"}}}}, #{title: "Update active call", description: "Modify an active call's behavior using new SWML instructions"})
-        @put update(@body request: CallUpdateRequest):
-        { @statusCode statusCode: 200; @body call: CallResponse; } |
-        StatusCode401 |
-        StatusCode404 |
-        CallUpdate422Error;
-    }
-
-    
-
-     
-}
+  @tag("Calls")
+  @friendlyName("Calls")
+  interface Calls {
+    @summary("Create a Call")
+    @doc("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`.")
+    create(@body request: CallCreateRequest):
+      | {
+          @statusCode statusCode: 201;
+          @body call: CallResponse;
+        }
+      | StatusCode401
+      | StatusCode404
+      | CallCreate422Error;
+
+    @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`.")
+    @opExample(
+      #{ parameters: holdCallExample },
+      #{
+        title: "Hold active call",
+        description: "Put an active AI call on hold, pausing the conversation",
+      }
+    )
+    @opExample(
+      #{ parameters: unholdCallExample },
+      #{
+        title: "Unhold active call",
+        description: "Resume an AI call that was previously put on hold",
+      }
+    )
+    @opExample(
+      #{ parameters: aiMessageExample },
+      #{
+        title: "Inject AI message",
+        description: "Send a message to the AI conversation to modify behavior or add context",
+      }
+    )
+    //@opExample(#{parameters: #{request: #{command: "update", params: #{id: "3fa85f64-5717-4562-b3fc-2c963f66afa6", url: "https://example.com/swml", fallback_url: "https://example.com/fallback"}}}}, #{title: "Update active call", description: "Modify an active call's behavior using new SWML instructions"})
+    @put
+    update(@body request: CallUpdateRequest):
+      | {
+          @statusCode statusCode: 200;
+          @body call: CallResponse;
+        }
+      | StatusCode401
+      | StatusCode404
+      | CallUpdate422Error;
+  }
+}

specs/signalwire-rest/_globally_shared/enums.tsp

@@ -1,57 +1,52 @@
 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")
+  id: string;
 
-    @doc("The unique identifier of the call on SignalWire. This can be used to update the call programmatically.")
-    @example("3fa85f64-5717-4562-b3fc-2c963f66afa6")
-    id: string;
+  @doc("The origin number or address.")
+  @example("sip:[email protected]")
+  from: string;
 
-    @doc("The origin number or address.")
-    @example("sip:from-sip@example-112233445566.sip.signalwire.com")
-    from: string;
+  @doc("The destination number or address.")
+  @example("sip:from-sip@example-112233445567.sip.signalwire.com")
+  to: string;
 
-    @doc("The destination number or address.")
-    @example("sip:[email protected]")
-    to: string;
+  @doc("The direction of the call.")
+  @example("outbound-api")
+  direction: "outbound-api";
 
-    @doc("The direction of the call.")
-    @example("outbound-api")
-    direction: "outbound-api";
+  @doc("The status of the call.")
+  @example("queued")
+  status: "answered" | "queued" | "initiated" | "ringing" | "ending" | "ended";
 
-    @doc("The status of the call.")
-    @example("queued")
-    status: "answered" | "queued" | "initiated" | "ringing" | "ending" | "ended";
+  @doc("The duration of the call in seconds.")
+  @example(60)
+  duration: integer;
 
-    @doc("The duration of the call in seconds.")
-    @example(60)
-    duration: integer;
+  @doc("The duration of the call in milliseconds.")
+  @example(60000)
+  duration_ms: integer;
 
-    @doc("The duration of the call in milliseconds.")
-    @example(60000)
-    duration_ms: integer;
+  @doc("The billable duration of the call in seconds.")
+  @example(60)
+  billable_duration: integer;
 
-    @doc("The billable duration of the call in seconds.")
-    @example(60)
-    billable_duration: integer;
+  @doc("Source of this call.")
+  @example("realtime_api")
+  source: "realtime_api";
 
-    @doc("Source of this call.")
-    @example("realtime_api")
-    source: "realtime_api";
-
-    @doc("Type of this call.")
-    @example("relay_sip_call")
-    type: "relay_pstn_call" | "relay_sip_call" | "relay_webrtc_call" ;
-
-    @doc("Details on charges associated with this call.")
-    charge: ChargeDetails[];
+  @doc("Type of this call.")
+  @example("relay_sip_call")
+  type: "relay_pstn_call" | "relay_sip_call" | "relay_webrtc_call";
 
+  @doc("Details on charges associated with this call.")
+  charge: ChargeDetails[];
 }
 
-
 model ChargeDetails {
+  @doc("Description for this charge.")
+  description: string;
 
-    @doc("Description for this charge.")
-    description: string;
-
-    @doc("Charged amount.")
-    amount: integer;
-
-}
+  @doc("Charged amount.")
+  amount: integer;
+}

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

@@ -1,36 +1,25 @@
 /**
  * Operation examples for the Calling API
- * 
+ *
  * These examples can be imported and used with @opExample decorator on operations
  */
-
 const callId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
 
 // Hangup Call Examples
 const hangupCallExample = #{
   request: #{
     id: callId,
     command: "calling.end",
-    params: #{
-      reason: "hangup"
-    }
-  }
+    params: #{ reason: "hangup" },
+  },
 };
 
 const holdCallExample = #{
-  request: #{
-    id: callId,
-    command: "calling.ai_hold",
-    params: #{}
-  }
+  request: #{ id: callId, command: "calling.ai_hold", params: #{} },
 };
 
 const unholdCallExample = #{
-  request: #{
-    id: callId,
-    command: "calling.ai_unhold", 
-    params: #{}
-  }
+  request: #{ id: callId, command: "calling.ai_unhold", params: #{} },
 };
 
 const aiMessageExample = #{
@@ -39,9 +28,9 @@ const aiMessageExample = #{
     command: "calling.ai_message",
     params: #{
       role: "system",
-      message_text: "You are now in expert mode. Provide detailed technical responses and use industry terminology."
-    }
-  }
+      message_text: "You are now in expert mode. Provide detailed technical responses and use industry terminology.",
+    },
+  },
 };
 
 const updateCallExample = #{
@@ -50,7 +39,7 @@ const updateCallExample = #{
     params: #{
       id: callId,
       url: "https://example.com/swml",
-      fallback_url: "https://example.com/fallback"
-    }
-  }
+      fallback_url: "https://example.com/fallback",
+    },
+  },
 };