@common-grants/core 0.1.1 → 0.2.0

package/lib/core/routes/applications.tsp

@@ -0,0 +1,66 @@
+import "../responses/index.tsp";
+
+// Define the top-level namespace for CommonGrants routes
+namespace CommonGrants.Routes;
+
+// Expose the contents of the Http and Rest namespaces
+// these include the decorators @route, @get, etc.
+using TypeSpec.Http;
+
+/** A re-usable interface for an Applications router
+ *
+ * To implement this interface, we recommend declaring a namespace,
+ * instantiating the router using `alias` (instead of `extends`),
+ * and decorating the namespace with `@route` and `@tag` since they aren't
+ * inherited directly from the interface.
+ */
+interface Applications {
+  // ##############################
+  // Start an application
+  // ##############################
+
+  @summary("Start an application")
+  @doc("Start a new application for a given competition.")
+  @post
+  @route("/start")
+  startApplication(
+    /** The ID of the competition to start an application for */
+    competitionId: Types.uuid,
+
+    /** The ID of the organization to start an application for, if applying on behalf of an organization */
+    organizationId?: Types.uuid,
+
+    /** The name of the application */
+    name: string,
+  ): Responses.Created<Models.ApplicationBase> | Responses.Unauthorized;
+
+  // ###############################
+  // Get an application
+  // ###############################
+
+  @summary("View an application")
+  @doc("View an application for a given competition, along with its form responses and validation errors.")
+  @get
+  @route("/{appId}")
+  getApplication(
+    /** The ID of the application to get */
+    @path appId: Types.uuid,
+  ): Responses.Ok<Models.ApplicationBase> | Responses.NotFound | Responses.Unauthorized;
+
+  // ###############################
+  // Submit an application
+  // ###############################
+
+  @summary("Submit an application")
+  @doc("Submit an application to a competition. Applications that have validation errors will be blocked from submitting until the errors are fixed.")
+  @put
+  @route("/{appId}/submit")
+  submitApplication(
+    /** The ID of the application to submit */
+    @path appId: Types.uuid,
+  ):
+    | Responses.Ok<unknown>
+    | Responses.ApplicationSubmissionError
+    | Responses.NotFound
+    | Responses.Unauthorized;
+}

package/lib/core/routes/competitions.tsp

@@ -0,0 +1,50 @@
+import "../responses/index.tsp";
+
+// Define the top-level namespace for CommonGrants routes
+namespace CommonGrants.Routes;
+
+// Expose the contents of the Http and Rest namespaces
+// these include the decorators @route, @get, etc.
+using TypeSpec.Http;
+
+/** A re-usable interface for a Competitions router
+ *
+ * To implement this interface, we recommend declaring a namespace,
+ * instantiating the router using `alias` (instead of `extends`),
+ * and decorating the namespace with `@route` and `@tag` since they aren't
+ * inherited directly from the interface.
+ */
+interface Competitions {
+  // ###############################
+  // View competition details
+  // ###############################
+
+  /** View details about a competition for a given funding opportunity.
+   *
+   * Each competition may have a distinct set of forms, be limited to a
+   * certain types of applicants, or have a different application period.
+   */
+  @summary("View competition details")
+  @get
+  @route("/{compId}")
+  read(
+    /** The ID of the competition to view */
+    @path compId: Types.uuid,
+  ): Responses.Ok<Models.CompetitionBase> | Responses.NotFound;
+
+  // ###############################
+  // Apply to a competition
+  // ###############################
+
+  @summary("Apply to a competition")
+  @doc("Apply to a given competition with all of the required information.")
+  @post
+  @route("/{compId}/apply")
+  apply(
+    /** The ID of the competition to apply to */
+    @path compId: Types.uuid,
+
+    /** The application to apply to the competition */
+    @body application: Models.ApplicationBase,
+  ): Responses.Created<Models.ApplicationBase> | Responses.NotFound | Responses.Unauthorized;
+}

package/lib/core/routes/form-responses.tsp

@@ -0,0 +1,52 @@
+import "../responses/index.tsp";
+
+// Define the top-level namespace for CommonGrants routes
+namespace CommonGrants.Routes;
+
+// Expose the contents of the Http and Rest namespaces
+// these include the decorators @route, @get, etc.
+using TypeSpec.Http;
+
+/** A re-usable interface for an Applications router
+ *
+ * To implement this interface, we recommend declaring a namespace,
+ * instantiating the router using `alias` (instead of `extends`),
+ * and decorating the namespace with `@route` and `@tag` since they aren't
+ * inherited directly from the interface.
+ */
+interface FormResponses {
+  // ###############################
+  // Update form response
+  // ###############################
+
+  @summary("Respond to a form")
+  @doc("Set or update the response to a given form in an application.")
+  @put
+  @route("/{appId}/forms/{formId}")
+  setFormResponse(
+    /** The ID of the application to whose form response is being updated */
+    @path appId: Types.uuid,
+
+    /** The ID of the form whose response is being updated */
+    @path formId: Types.uuid,
+
+    /** The response to the form */
+    @body response: Record<unknown>,
+  ): Responses.Ok<Models.AppFormResponse>;
+
+  // ###############################
+  // Get form response
+  // ###############################
+
+  @summary("Get a form response")
+  @doc("Get the response to a given form in an application.")
+  @get
+  @route("/{appId}/forms/{formId}")
+  getFormResponse(
+    /** The ID of the application to whose form response is being retrieved */
+    @path appId: Types.uuid,
+
+    /** The ID of the form whose response is being retrieved */
+    @path formId: Types.uuid,
+  ): Responses.Ok<Models.AppFormResponse>;
+}

package/lib/core/routes/forms.tsp

@@ -0,0 +1,38 @@
+import "../responses/index.tsp";
+
+// Define the top-level namespace for CommonGrants routes
+namespace CommonGrants.Routes;
+
+// Expose the contents of the Http and Rest namespaces
+// these include the decorators @route, @get, etc.
+using TypeSpec.Http;
+
+/** A re-usable interface for an Applications router
+ *
+ * To implement this interface, we recommend declaring a namespace,
+ * instantiating the router using `alias` (instead of `extends`),
+ * and decorating the namespace with `@route` and `@tag` since they aren't
+ * inherited directly from the interface.
+ */
+interface Forms {
+  // ###############################
+  // Update form response
+  // ###############################
+
+  @summary("List forms")
+  @doc("Get a paginated list of forms, sorted by `lastModifiedAt` with most recent first.")
+  @get
+  list(...Pagination.PaginatedQueryParams): Responses.Paginated<Models.Form>;
+
+  // ###############################
+  // View form details
+  // ###############################
+
+  @summary("View form details")
+  @doc("View details about a given form.")
+  @get
+  read(
+    /** The ID of the form to view */
+    @path formId: Types.uuid,
+  ): Responses.Ok<Models.Form>;
+}

package/lib/core/routes/index.tsp

@@ -3,6 +3,10 @@ import "@typespec/rest";
 
 // Import individual route files to provide a consistent interface
 import "./opportunities.tsp";
+import "./applications.tsp";
+import "./form-responses.tsp";
+import "./forms.tsp";
+import "./competitions.tsp";
 
 /** A series of routing interfaces for CommonGrants API endpoints
  *

package/lib/core/routes/opportunities.tsp

@@ -8,6 +8,7 @@ namespace CommonGrants.Routes;
 // Expose the contents of the Http and Rest namespaces
 // these include the decorators @route, @get, etc.
 using TypeSpec.Http;
+using TypeSpec.Versioning;
 
 /** A re-usable interface for an Opportunities router
  *
@@ -52,7 +53,7 @@ interface Opportunities {
   ): Responses.Paginated<T>;
 
   // ##############################
-  // View an opportunity
+  // View an opportunity (v0.1.0)
   // ##############################
 
   /** `GET /opportunities/<id>` View opportunity details
@@ -60,12 +61,19 @@ interface Opportunities {
    * @template T Type of the response model.
    * Must be an extension of Schemas.OpportunityBase. Default is Schemas.OpportunityBase.
    */
-  @summary("View opportunity")
-  @doc("View additional details about an opportunity")
+  @summary("View opportunity details")
+  @doc("View details about an opportunity.")
   @get
-  read<T extends Models.OpportunityBase = Models.OpportunityBase>(
+  read<T extends Models.OpportunityBase = Models.OpportunityDetails>(
     /** The ID of the opportunity to view */
-    @path id: Types.uuid,
+    @path
+    @removed(Versions.v0_2)
+    id: Types.uuid,
+
+    /** The ID of the opportunity to view */
+    @path
+    @added(Versions.v0_2)
+    oppId: Types.uuid,
   ): Responses.Ok<T> | Responses.NotFound;
 
   // ###############################
@@ -78,7 +86,7 @@ interface Opportunities {
    * Must be an extension of Schemas.OpportunityBase. Default is Schemas.OpportunityBase.
    */
   @summary("Search opportunities")
-  @doc("Search for opportunities based on the provided filters")
+  @doc("Search for opportunities based on the provided filters.")
   @post
   @route("/search")
   search<T extends Models.OpportunityBase = Models.OpportunityBase>(

package/lib/main.tsp

@@ -3,7 +3,19 @@
 // https://typespec.io/docs/extending-typespec/basics/#h-add-your-main-typespec-file
 import "../dist/src/index.js";
 
+// Import the core typespec files
 import "./core/index.tsp";
 import "./api.tsp";
 
+// Import the versioning package
+import "@typespec/versioning";
+
+using Versioning;
+
+@versioned(Versions)
 namespace CommonGrants;
+
+enum Versions {
+  v0_1: "0.1.0",
+  v0_2: "0.2.0",
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common-grants/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",
@@ -55,7 +55,8 @@
     "@typespec/http": "^1.1.0",
     "@typespec/json-schema": "1.0.0",
     "@typespec/openapi3": "1.0.0",
-    "@typespec/rest": "0.70.0"
+    "@typespec/rest": "0.70.0",
+    "@typespec/versioning": "^0.70.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.6",