PubSub TypeSpec conversion

specs/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "build": "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",
+    "build": "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:calling-api": "cd ./signalwire-rest/calling-api && 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 ../../",
@@ -12,17 +12,18 @@
     "build:fax-api": "cd ./signalwire-rest/fax-api && tsp compile . && cd ../../",
     "build:message-api": "cd ./signalwire-rest/message-api && tsp compile . && cd ../../",
     "build:voice-api": "cd ./signalwire-rest/voice-api && tsp compile . && cd ../../",
+    "build:pubsub-api": "cd ./signalwire-rest/pubsub-api && tsp compile . && cd ../../",
     "clean": "echo 'Skipping clean step'",
     "prebuild": "yarn clean",
     "format": "tsp format **/*.tsp",
     "format:check": "tsp format --check **/*.tsp"
   },
   "dependencies": {
-    "@typespec/compiler": "1.2.1",
-    "@typespec/http": "1.2.1",
-    "@typespec/openapi": "1.2.1",
-    "@typespec/openapi3": "1.2.1",
-    "@typespec/rest": "0.72.1"
+    "@typespec/compiler": "1.3.0",
+    "@typespec/http": "1.3.0",
+    "@typespec/openapi": "1.3.0",
+    "@typespec/openapi3": "1.3.0",
+    "@typespec/rest": "0.73.0"
   },
   "devDependencies": {
     "typescript": "^5.5.4"

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

@@ -0,0 +1,38 @@
+import "@typespec/http";
+import "@typespec/openapi";
+import "../types";
+import "./tokens";
+import "../_globally_shared/const.tsp";
+import "./tags.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+using Types.StatusCodes;
+
+@tagMetadata(TOKENS_TAG, TOKENS_TAG_METADATA)
+@externalDocs(
+  "https://developer.signalwire.com",
+  "Find more information about this and other SignalWire APIs."
+)
+@info(#{
+  title: "PubSub API",
+  version: "1.0.0",
+  contact: CONTACT_INFO,
+  license: LICENSE_INFO,
+  termsOfService: TERMS_OF_SERVICE,
+})
+@service(#{ title: "PubSub API" })
+@server(
+  "https://{space_name}.${SERVER_URL}/pubsub",
+  "Endpoint",
+  {
+    @doc(SERVER_URL_DESCRIPTION)
+    @example("example")
+    space_name: string = "{Your_Space_Name}",
+  }
+)
+@useAuth(BasicAuth)
+@doc("""
+  An API to use PubSub channels in your own application.
+  """)
+namespace PubSubAPI;

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

@@ -0,0 +1,11 @@
+import "@typespec/openapi3";
+
+const TOKENS_TAG = "Tokens";
+
+const TOKENS_TAG_METADATA = #{
+  description: "Endpoints related to creating & managing PubSub Tokens",
+  externalDocs: #{
+    url: "https://developer.signalwire.com/rest/signalwire-rest/endpoints/pubsub/tokens",
+    description: "Developer documentation on PubSub API endpoints",
+  },
+};

specs/signalwire-rest/pubsub-api/tokens/main.tsp

@@ -0,0 +1,43 @@
+import "@typespec/http";
+import "@typespec/openapi";
+import "../../types";
+import "./models/core.tsp";
+import "./models/requests.tsp";
+import "./models/responses.tsp";
+import "../tags.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+using Types.StatusCodes;
+
+@route("/tokens")
+namespace PubSubAPI.Tokens {
+  @tag(TOKENS_TAG)
+  @friendlyName("Tokens")
+  interface PubSubTokens {
+    @summary("Generate a new PubSub Token")
+    @doc("""
+      Generate a PubSub Token to be used to authenticate clients to the PubSub Service.
+
+
+      #### Permissions
+
+      The API token must include the following scopes: _PubSub_.
+      """)
+    @post
+    @operationId("create_token")
+    create(@body request: NewPubSubToken):
+      | {
+          @statusCode _: 200;
+          @doc("OK")
+          @body token: PubSubToken;
+        }
+      | StatusCode401
+      | {
+          @statusCode _: 422;
+          @doc("Unprocessable Entity. You may have specified invalid parameters.")
+          @body error: PubSubToken422Error;
+        }
+      | StatusCode500;
+  }
+}

specs/signalwire-rest/pubsub-api/tokens/models/core.tsp

@@ -0,0 +1,5 @@
+model PubSubToken {
+  @doc("A PubSub Token to be used to authenticate clients to the PubSub Service.")
+  @example("eyJ0eXAiOiJWUlQiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MjIxMjAxMjMsI...wMCwicnNlIjo5MDB9-BqG-DqC5LhpsdMWEFjhVkTBpQ")
+  token: string;
+}

specs/signalwire-rest/pubsub-api/tokens/models/requests.tsp

@@ -0,0 +1,53 @@
+/* Model is used to work-around a bug in the rest api plugin, not a TypeSpec issue. Duplicate description must be present and usage of a model is required.
+Otherwise the property will render a additionalProperty with the exact same description as the top level property holding additionalProperties. */
+@doc("An arbitrary JSON object available to store stateful application information in. Must be valid JSON and have a maximum size of 2,000 characters.")
+@example(#{
+  display_name: "Joe",
+  an_array: #["foo", "bar", "baz"],
+})
+model PubSubState is Record<unknown>;
+
+model NewPubSubToken {
+  @minValue(1)
+  @maxValue(43200)
+  @example(15)
+  @doc("The maximum time, in minutes, for which the access token will be valid. Between 1 and 43,200 (30 days).")
+  ttl: integer;
+
+  channels: PubSubChannels;
+
+  @doc("The unique identifier of the member. Up to 250 characters. If not specified, a random UUID will be generated.")
+  @example("John Doe")
+  @maxLength(250)
+  member_id?: string;
+
+  /* Model is used to work-around a bug in the rest api plugin, not a TypeSpec issue. Duplicate description must be present and usage of a model is required.
+    Otherwise the property will render a additionalProperty with the exact same description as the top level property holding additionalProperties. */
+  @doc("An arbitrary JSON object available to store stateful application information in. Must be valid JSON and have a maximum size of 2,000 characters.")
+  state?: PubSubState;
+}
+
+@doc("""
+  Each channel with `write` and `read` objects with boolean as values. Max of 500 channels inside main `channels`. 
+  Either `read`, `write`, or both are required inside each channel and default to false. 
+  Each channel name can be up to 250 characters. Must be valid JSON.
+  """)
+@example(#{
+  channela: #{ read: true, write: false },
+  channelb: #{ read: true },
+})
+model PubSubChannels {
+  ...PubSubPermissions;
+}
+
+@doc("PubSub Permissions for a channel.")
+model PubSubPermissions
+  is Record<{
+    @doc("Gives the token read access to the channel.")
+    @example(true)
+    read?: boolean;
+
+    @doc("Gives the token write access to the channel.")
+    @example(false)
+    write?: boolean;
+  }>;

specs/signalwire-rest/pubsub-api/tokens/models/responses.tsp

@@ -0,0 +1,27 @@
+import "@typespec/http";
+import "../../../types/status-codes";
+
+using TypeSpec.Http;
+
+model PubSubToken422Error {
+  @doc("Error type.")
+  @example("validation_error")
+  type: string;
+
+  @doc("Error code.")
+  @example("not_a_valid_json")
+  code: string;
+
+  @doc("Error details.")
+  @example("Permissions must be valid JSON")
+  message: string;
+
+  @doc("Request parameter associated with this error.")
+  @example("permissions")
+  attribute: string;
+
+  @doc("Link to developer resource for this error.")
+  @format("uri")
+  @example("https://developer.signalwire.com/rest/overview/error-codes/#not_a_valid_json")
+  url: string;
+}