Decouple SWML schemas from REST operation models

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

@@ -15,28 +15,16 @@ const dialCallExample = #{
     command: "dial",
     params: #{
       from: "+15551234567",
-      to: "sip:alice@sip.example.com",
-      url: "https://example.com/swml",
-      caller_id: "+15551234567",
-      username: "alice",
-      password: "s3cr3t",
-      status_url: "https://example.com/status_callback",
-      status_events: #["answered", "ended"],
-      codecs: #[OutboundCallCodec.PCMU, OutboundCallCodec.PCMA],
-      timeout: 30,
-      max_price_per_minute: 0.05,
+      to: "+15557654321",
+      swml: CallSWMLDocumentExample,
     },
   },
 };
 
 const updateCallExample = #{
   request: #{
     command: "update",
-    params: #{
-      id: callId,
-      url: "https://example.com/swml",
-      fallback_url: "https://example.com/fallback",
-    },
+    params: #{ id: callId, swml: CallSWMLDocumentExample },
   },
 };
 
@@ -499,7 +487,7 @@ const transferCallExample = #{
   request: #{
     command: "calling.transfer",
     id: callId,
-    params: #{ dest: "sip:destination@example.com" },
+    params: #{ dest: CallSWMLDocumentExample },
   },
 };
 

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

@@ -1,7 +1,8 @@
 import "@typespec/http";
 import "@typespec/openapi3";
 import "@typespec/json-schema";
-import "../../../../swml/calling";
+import "../../../../swml/calling/Methods/ai_sidecar";
+import "../../../../swml/calling/Methods/live_translate";
 import "./core.tsp";
 
 using TypeSpec.Http;
@@ -14,6 +15,13 @@ using SWML.Calling;
 
 const CallSWMLExample = "{'version': '1.0.0', 'sections': { 'main': [{ 'answer': { 'max_duration': 60 }},{ 'play': { 'urls': ['silence:2', 'say:Hello from SignalWire!']}}]}}";
 
+const CallSWMLDocumentExample = #{
+  version: "1.0.0",
+  sections: #{
+    main: #[#{ play: #{ url: "https://cdn.signalwire.com/swml/audio.mp3" } }],
+  },
+};
+
 const CallFallbackURLExample = "https://example.com/fallback";
 
 const CallSWMLURLExample = "https://example.com/swml";
@@ -425,9 +433,10 @@ model CallCreateParamsBase {
   @example("s3cr3t")
   password?: string;
 
-  @doc("Inline SWML document (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted.")
+  @doc("Inline [Calling SWML document](/docs/swml/reference/calling) (JSON or YAML string), or an `http(s)://` URL that returns one, executed at the destination end. Useful for directing the call to a RelayBin / external SWML handler. When present, `to` may be omitted.")
   @example("https://example.com/destination.swml.json")
-  to_script?: string | SWMLObject;
+  @example(CallSWMLDocumentExample)
+  to_script?: string | TypeSpec.Record<unknown>;
 
   @doc("Caller ID displayed to the destination. E.164 for PSTN; short caller-id token or SIP URI for SIP/Verto.")
   @example("+1234567890")
@@ -501,8 +510,9 @@ model CallCreateParamsURL is CallCreateParamsBase {
 
 @summary("dial (Inline SWML)")
 model CallCreateParamsSWML is CallCreateParamsBase {
-  @doc("Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.")
-  swml: SWMLObject;
+  @doc("Inline [Calling SWML document](/docs/swml/reference/calling) containing instructions for handling the call. Either `url` or `swml` must be included for a new call.")
+  @example(CallSWMLDocumentExample)
+  swml: TypeSpec.Record<unknown>;
 }
 
 @summary("update")
@@ -529,8 +539,9 @@ model CallUpdateParamsBase {
 
 @summary("update (Inline SWML)")
 model CallUpdateParamsSWML is CallUpdateParamsBase {
-  @doc("Inline SWML object containing SWML instructions for handling the call. Either `url` or `swml` must be included for a new call.")
-  swml: SWMLObject;
+  @doc("Inline [Calling SWML document](/docs/swml/reference/calling) containing instructions for handling the call. Either `url` or `swml` must be included for a new call.")
+  @example(CallSWMLDocumentExample)
+  swml: TypeSpec.Record<unknown>;
 }
 
 @summary("update (URL)")
@@ -1916,9 +1927,10 @@ model CallTransferRequest {
 
   @doc(paramsDescription)
   params: {
-    @doc("The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline SWML object.")
+    @doc("The destination to transfer the call to. Can be a SIP URI, phone number, SWML URL, or an inline [Calling SWML document](/docs/swml/reference/calling).")
     @example("sip:destination@example.com")
-    dest: string | SWMLObject;
+    @example(CallSWMLDocumentExample)
+    dest: string | TypeSpec.Record<unknown>;
   };
 }
 

specs/signalwire-rest/fabric-api/_shared/examples.tsp

@@ -0,0 +1,131 @@
+import "./const.tsp";
+import "./enums.tsp";
+
+const FABRIC_RESOURCE_ID_EXAMPLE = "993ed018-9e79-4e50-b97b-984bd5534095";
+const FABRIC_PROJECT_ID_EXAMPLE = "1313fe58-5e14-4c11-bbe7-6fdfa11fe780";
+const FABRIC_CREATED_AT_EXAMPLE = utcDateTime.fromISO("2024-05-06T12:20:00Z");
+const FABRIC_UPDATED_AT_EXAMPLE = utcDateTime.fromISO("2024-05-06T12:25:00Z");
+
+const AI_AGENT_REQUEST_EXAMPLE = #{
+  prompt: #{ text: "You are a helpful customer support assistant." },
+  name: "Support Assistant",
+};
+
+const AI_AGENT_EXAMPLE = #{
+  prompt: #{ text: "You are a helpful customer support assistant." },
+  agent_id: "a87db7ed-8ebe-42e4-829f-8ba5a4152f54",
+  name: "Support Assistant",
+};
+
+const AI_AGENT_RESPONSE_EXAMPLE = #{
+  id: FABRIC_RESOURCE_ID_EXAMPLE,
+  project_id: FABRIC_PROJECT_ID_EXAMPLE,
+  display_name: "Support Assistant",
+  type: FabricResponseType.AiAgent,
+  created_at: FABRIC_CREATED_AT_EXAMPLE,
+  updated_at: FABRIC_UPDATED_AT_EXAMPLE,
+  ai_agent: AI_AGENT_EXAMPLE,
+};
+
+const CALL_FLOW_EXAMPLE = #{
+  id: FABRIC_RESOURCE_ID_EXAMPLE,
+  title: "Welcome Call Flow",
+  flow_data: #{},
+  relayml: SWML_CONTENTS_EXAMPLE,
+  document_version: 1,
+};
+
+const CALL_FLOW_RESPONSE_EXAMPLE = #{
+  id: FABRIC_RESOURCE_ID_EXAMPLE,
+  project_id: FABRIC_PROJECT_ID_EXAMPLE,
+  display_name: "Welcome Call Flow",
+  type: FabricResponseType.CallFlow,
+  created_at: FABRIC_CREATED_AT_EXAMPLE,
+  updated_at: FABRIC_UPDATED_AT_EXAMPLE,
+  call_flow: CALL_FLOW_EXAMPLE,
+};
+
+const CALL_FLOW_VERSION_EXAMPLE = #{
+  id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  version: "1.0.0",
+  created_at: "2024-05-06T12:20:00Z",
+  updated_at: "2024-05-06T12:25:00Z",
+  flow_data: #{},
+  relayml: SWML_CONTENTS_EXAMPLE,
+};
+
+const CALLING_SWML_SCRIPT_EXAMPLE = #{
+  id: FABRIC_RESOURCE_ID_EXAMPLE,
+  display_name: "Welcome Script",
+  script_type: "calling",
+  request_url: "https://example.signalwire.com/api/fabric/resources/swml_scripts/993ed018-9e79-4e50-b97b-984bd5534095",
+  contents: SWML_CONTENTS_EXAMPLE,
+};
+
+const MESSAGING_SWML_SCRIPT_EXAMPLE = #{
+  id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  display_name: "Reply Bot",
+  script_type: "messaging",
+  request_url: "https://example.signalwire.com/api/fabric/resources/swml_scripts/3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  contents: SWML_MESSAGING_CONTENTS_EXAMPLE,
+};
+
+const CALLING_SWML_SCRIPT_RESPONSE_EXAMPLE = #{
+  id: FABRIC_RESOURCE_ID_EXAMPLE,
+  project_id: FABRIC_PROJECT_ID_EXAMPLE,
+  display_name: "Welcome Script",
+  type: FabricResponseType.SwmlScript,
+  created_at: FABRIC_CREATED_AT_EXAMPLE,
+  updated_at: FABRIC_UPDATED_AT_EXAMPLE,
+  swml_script: CALLING_SWML_SCRIPT_EXAMPLE,
+};
+
+const MESSAGING_SWML_SCRIPT_RESPONSE_EXAMPLE = #{
+  id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  project_id: FABRIC_PROJECT_ID_EXAMPLE,
+  display_name: "Reply Bot",
+  type: FabricResponseType.SwmlScript,
+  created_at: FABRIC_CREATED_AT_EXAMPLE,
+  updated_at: FABRIC_UPDATED_AT_EXAMPLE,
+  swml_script: MESSAGING_SWML_SCRIPT_EXAMPLE,
+};
+
+const RESOURCE_AI_EXAMPLE = #{
+  id: FABRIC_RESOURCE_ID_EXAMPLE,
+  project_id: FABRIC_PROJECT_ID_EXAMPLE,
+  display_name: "Support Assistant",
+  created_at: FABRIC_CREATED_AT_EXAMPLE,
+  updated_at: FABRIC_UPDATED_AT_EXAMPLE,
+  type: FabricResponseType.AiAgent,
+  ai_agent: AI_AGENT_EXAMPLE,
+};
+
+const RESOURCE_CALL_FLOW_EXAMPLE = #{
+  id: FABRIC_RESOURCE_ID_EXAMPLE,
+  project_id: FABRIC_PROJECT_ID_EXAMPLE,
+  display_name: "Welcome Call Flow",
+  created_at: FABRIC_CREATED_AT_EXAMPLE,
+  updated_at: FABRIC_UPDATED_AT_EXAMPLE,
+  type: FabricResponseType.CallFlow,
+  call_flow: CALL_FLOW_EXAMPLE,
+};
+
+const RESOURCE_CALLING_SWML_SCRIPT_EXAMPLE = #{
+  id: FABRIC_RESOURCE_ID_EXAMPLE,
+  project_id: FABRIC_PROJECT_ID_EXAMPLE,
+  display_name: "Welcome Script",
+  created_at: FABRIC_CREATED_AT_EXAMPLE,
+  updated_at: FABRIC_UPDATED_AT_EXAMPLE,
+  type: FabricResponseType.SwmlScript,
+  swml_script: CALLING_SWML_SCRIPT_EXAMPLE,
+};
+
+const RESOURCE_MESSAGING_SWML_SCRIPT_EXAMPLE = #{
+  id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  project_id: FABRIC_PROJECT_ID_EXAMPLE,
+  display_name: "Reply Bot",
+  created_at: FABRIC_CREATED_AT_EXAMPLE,
+  updated_at: FABRIC_UPDATED_AT_EXAMPLE,
+  type: FabricResponseType.SwmlScript,
+  swml_script: MESSAGING_SWML_SCRIPT_EXAMPLE,
+};

specs/signalwire-rest/fabric-api/ai-agent/main.tsp

@@ -7,6 +7,7 @@ import "./models/errors.tsp";
 import "./addresses";
 import "../../types";
 import "../tags.tsp";
+import "../_shared/examples.tsp";
 import "../../../_shared/alias/token-permissions.tsp";
 
 using TypeSpec.Http;
@@ -25,6 +26,18 @@ namespace SignalWireAPI.Fabric.AIAgents {
 
       ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">}
       """)
+    @opExample(
+      #{
+        returnType: #{
+          data: #[AI_AGENT_RESPONSE_EXAMPLE],
+          links: #{
+            self: "https://example.signalwire.com/api/fabric/resources/ai_agents?page_number=0&page_size=50",
+            first: "https://example.signalwire.com/api/fabric/resources/ai_agents?page_number=0&page_size=50",
+          },
+        },
+      },
+      #{ title: "AI agent list", description: "A page containing one AI agent." }
+    )
     list(): AIAgentListResponse | StatusCode401 | StatusCode404 | StatusCode500;
 
     @operationId("get_ai_agent")
@@ -34,6 +47,10 @@ namespace SignalWireAPI.Fabric.AIAgents {
 
       ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">}
       """)
+    @opExample(
+      #{ returnType: #{ statusCode: 200, ai_agent: AI_AGENT_RESPONSE_EXAMPLE } },
+      #{ title: "AI agent", description: "A customer support AI agent." }
+    )
     read(...AIAgentPathID):
       | {
           @statusCode statusCode: 200;
@@ -50,6 +67,16 @@ namespace SignalWireAPI.Fabric.AIAgents {
 
       ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">}
       """)
+    @opExample(
+      #{
+        parameters: AI_AGENT_REQUEST_EXAMPLE,
+        returnType: #{ statusCode: 201, ai_agent: AI_AGENT_RESPONSE_EXAMPLE },
+      },
+      #{
+        title: "Customer support agent",
+        description: "Create an AI agent with a concise text prompt.",
+      }
+    )
     @post
     create(...AIAgentCreateRequest):
       | {
@@ -68,6 +95,20 @@ namespace SignalWireAPI.Fabric.AIAgents {
 
       ${tokenPermissions<"_Voice_, _Messaging_, _Fax_, or _Video_">}
       """)
+    @opExample(
+      #{
+        parameters: #{
+          id: "993ed018-9e79-4e50-b97b-984bd5534095",
+          prompt: #{ text: "You are a concise customer support assistant." },
+          name: "Support Assistant",
+        },
+        returnType: #{ statusCode: 200, ai_agent: AI_AGENT_RESPONSE_EXAMPLE },
+      },
+      #{
+        title: "Update the agent prompt",
+        description: "Replace an AI agent's prompt while leaving its other settings unchanged.",
+      }
+    )
     @patch(#{ implicitOptionality: true })
     update(...AIAgentPathID, ...AIAgentUpdateRequest):
       | {