@common-grants/core 0.1.0-alpha.11 → 0.1.0-alpha.13

package/README.md

@@ -101,9 +101,7 @@ import "./routes.tsp"; // Import the routes from above
 using TypeSpec.Http;
 
 /** Description of your API goes here */
-@service({
-  title: "Custom API",
-})
+@service(#{ title: "Custom API" })
 namespace CustomAPI;
 ```
 

package/lib/api.tsp

@@ -11,9 +11,21 @@ using TypeSpec.OpenAPI;
  * In order for an API to be "compliant" with the CommonGrants protocol,
  * it must implement all of the routes with the "required" tag in this specification.
  */
-@service({
-  title: "CommonGrants Base API",
-})
+@service(#{ title: "CommonGrants Base API" })
+@tagMetadata(
+  "optional",
+  #{ description: "Endpoints that MAY be implemented by CommonGrants APIs" }
+)
+@tagMetadata(
+  "required",
+  #{
+    description: "Endpoints that MUST be implemented by all CommonGrants APIs",
+  }
+)
+@tagMetadata(
+  "Opportunities",
+  #{ description: "Endpoints related to funding opportunities" }
+)
 namespace CommonGrants.API;
 
 @tag("Opportunities")

package/lib/core/pagination.tsp

@@ -35,7 +35,7 @@ model PaginatedBodyParams {
 }
 
 /** Details about the paginated results */
-model PaginationInfo {
+model PaginatedResultsInfo {
   /** Current page number (indexing starts at 1) */
   @example(1)
   @minValue(1)

package/lib/core/responses/success.tsp

@@ -75,7 +75,7 @@ model Paginated<T> extends Success {
   items: T[];
 
   /** Details about the paginated results */
-  paginationInfo: Pagination.PaginationInfo;
+  paginationInfo: Pagination.PaginatedResultsInfo;
 }
 
 // ############################################################################
@@ -103,7 +103,7 @@ model Sorted<T> {
   ...Paginated<T>;
 
   /** The sort order of the items */
-  sortInfo: Sorting.SortInfo;
+  sortInfo: Sorting.SortedResultsInfo;
 }
 
 // ############################################################################
@@ -137,5 +137,10 @@ model Filtered<ItemsT, FilterT> extends Success {
   ...Sorted<ItemsT>;
 
   /** The filters applied to the response items */
-  filterInfo: FilterT;
+  filterInfo: {
+    filters: FilterT;
+
+    /** Non-fatal errors that occurred during filtering */
+    errors?: string[];
+  };
 }

package/lib/core/routes/opportunities.tsp

@@ -49,7 +49,7 @@ interface Opportunities {
   @list
   list<T extends Models.OpportunityBase = Models.OpportunityBase>(
     ...Pagination.PaginatedQueryParams,
-  ): Responses.Paginated<T> | Responses.Unauthorized;
+  ): Responses.Paginated<T>;
 
   // ##############################
   // View an opportunity
@@ -66,7 +66,7 @@ interface Opportunities {
   read<T extends Models.OpportunityBase = Models.OpportunityBase>(
     /** The ID of the opportunity to view */
     @path id: Types.uuid,
-  ): Responses.Ok<T> | Responses.NotFound | Responses.Unauthorized;
+  ): Responses.Ok<T> | Responses.NotFound;
 
   // ###############################
   // Search opportunities
@@ -82,6 +82,10 @@ interface Opportunities {
   @post
   @route("/search")
   search<T extends Models.OpportunityBase = Models.OpportunityBase>(
+    /** Opportunity search query */
+    @example("Pre-school education")
+    search?: string,
+
     /** Filters to apply to the opportunity search
      *
      * Multiple filter conditions will be combined with AND logic, so that
@@ -94,5 +98,5 @@ interface Opportunities {
 
     /** Pagination instructions for the results */
     pagination?: Pagination.PaginatedBodyParams,
-  ): Responses.Filtered<T, Models.OppFilters> | Responses.Unauthorized;
+  ): Responses.Filtered<T, Models.OppFilters>;
 }

package/lib/core/sorting.tsp

@@ -57,16 +57,19 @@ model SortBodyParams {
 }
 
 /** Information about the sort order of the items returned */
-model SortInfo {
-  /** The field to sort by */
+model SortedResultsInfo {
+  /** The field results are sorted by, or "custom" if an implementation-defined sort key is used */
   @example("lastModifiedAt")
   sortBy: string;
 
-  /** Implementation-defined sort key */
+  /** Implementation-defined sort key used to sort the results, if applicable */
   @example("customField")
   customSortBy?: string;
 
-  /** The order to sort by */
+  /** The order in which the results are sorted, e.g. ascending or descending */
   @example(SortOrder.asc)
-  sortOrder?: SortOrder;
+  sortOrder: SortOrder;
+
+  /** Non-fatal errors that occurred during sorting */
+  errors?: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common-grants/core",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",
@@ -55,11 +55,11 @@
   "author": "CommonGrants",
   "license": "CC0-1.0",
   "peerDependencies": {
-    "@typespec/compiler": "^0.63.0",
-    "@typespec/http": "^0.63.0",
-    "@typespec/json-schema": "^0.63.0",
-    "@typespec/openapi3": "^0.63.0",
-    "@typespec/rest": "^0.63.0"
+    "@typespec/compiler": "^0.66.0",
+    "@typespec/http": "^0.66.0",
+    "@typespec/json-schema": "^0.66.0",
+    "@typespec/openapi3": "^0.66.0",
+    "@typespec/rest": "^0.66.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.6",