@common-grants/core 0.1.0-alpha.8 → 0.1.0

package/lib/core/responses/success.tsp

@@ -1,6 +1,12 @@
+import "../pagination.tsp";
+import "../sorting.tsp";
 import "@typespec/http";
 
-namespace Core.Responses;
+namespace CommonGrants.Responses;
+
+// ############################################################################
+// Default success response
+// ############################################################################
 
 model Success {
   @example(200)
@@ -10,13 +16,16 @@ model Success {
   message: string;
 }
 
+// ############################################################################
+// 200 response
+// ############################################################################
+
 /** Template for a 200 response with data
  *
  * @template T The schema for the value of the `"data"` property in this response
  * @example How to specify a custom 200 response model
  *
  * ```typespec
- *
  * // Define a model
  * model CustomModel {
  *   id: string;
@@ -24,7 +33,7 @@ model Success {
  * }
  *
  * // Pass that model to the `Ok` template
- * alias CustomModel200 = Success.Ok<CustomModel>;
+ * alias CustomModel200 = Responses.Ok<CustomModel>;
  * ```
  */
 @doc("A 200 response with data")
@@ -36,13 +45,16 @@ model Ok<T> extends Success {
   data: T;
 }
 
+// ############################################################################
+// 200 paginated response
+// ############################################################################
+
 /** Template for a 200 response with paginated list of items
  *
  * @template T The schema for the value of the `"items"` property in this response
  * @example How to specify a custom paginated response model
  *
  * ```typespec
- *
  * // Define a model
  * model CustomModel {
  *   id: string;
@@ -50,7 +62,7 @@ model Ok<T> extends Success {
  * }
  *
  * // Pass that model to the `Ok` template
- * alias CustomModelResponse = Success.Paginated<CustomModel>;
+ * alias CustomModelResponse = Responses.Paginated<CustomModel>;
  * ```
  */
 @doc("A 200 response with a paginated list of items")
@@ -63,29 +75,72 @@ model Paginated<T> extends Success {
   items: T[];
 
   /** Details about the paginated results */
-  paginationInfo: {
-    /** Current page number (indexing starts at 1) */
-    @example(1)
-    page: int32;
-
-    /** Number of items per page */
-    @example(20)
-    pageSize: integer;
-
-    /** Total number of items across all pages */
-    @example(100)
-    totalItems: integer;
-
-    /** Total number of pages */
-    @example(5)
-    totalPages: integer;
-
-    /** URL for the next page if available */
-    @example("/opportunities?page=2&pageSize=20")
-    nextPageUrl?: string;
-
-    /** URL for the previous page if available */
-    @example("/opportunities?page=1&pageSize=20")
-    previousPageUrl?: string;
+  paginationInfo: Pagination.PaginatedResultsInfo;
+}
+
+// ############################################################################
+// 200 sorted response
+// ############################################################################
+
+/** A paginated list of items with a sort order
+ *
+ * @template T The schema for the value of the `"items"` property in this response
+ * @example How to specify a custom sorted response model
+ *
+ * ```typespec
+ * // Define a model
+ * model CustomModel {
+ *   id: string;
+ *   description: string;
+ * }
+ *
+ * // Pass that model to the `Sorted` template
+ * alias CustomModelSortedResponse = Responses.Sorted<CustomModel>;
+ * ```
+ */
+model Sorted<T> {
+  // Inherit the properties of the Paginated response
+  ...Paginated<T>;
+
+  /** The sort order of the items */
+  sortInfo: Sorting.SortedResultsInfo;
+}
+
+// ############################################################################
+// 200 filtered response
+// ############################################################################
+
+/** A paginated list of items with a filter
+ *
+ * @template ItemsT The schema for the value of the `"items"` property in this response
+ * @template FilterT The schema for the value of the `"filter"` property in this response
+ * @example How to specify a custom filtered response model
+ *
+ * ```typespec
+ * // Define a model for the items in the response
+ * model CustomModel {
+ *   id: string;
+ *   description: string;
+ * }
+ *
+ * // Define a model for the filter in the response
+ * model CustomFilter extends Record<Filters.DefaultFilter> {
+ *   lastModifiedAt: Filters.DateComparisonFilter;
+ * }
+ *
+ * // Pass that model to the `Filtered` template
+ * alias CustomModelFilteredResponse = Responses.Filtered<CustomModel, CustomFilter>;
+ * ```
+ */
+model Filtered<ItemsT, FilterT> extends Success {
+  // Inherit the properties of the Sorted response
+  ...Sorted<ItemsT>;
+
+  /** The filters applied to the response items */
+  filterInfo: {
+    filters: FilterT;
+
+    /** Non-fatal errors that occurred during filtering */
+    errors?: string[];
   };
 }

package/lib/core/routes/index.tsp

@@ -4,20 +4,19 @@ import "@typespec/rest";
 // Import individual route files to provide a consistent interface
 import "./opportunities.tsp";
 
-/** A series of interfaces for CommonGrants API routes
+/** A series of routing interfaces for CommonGrants API endpoints
  *
  * @example How to use the `Routes` namespace
  *
- * ```tsp
+ * ```typespec
  * import "@common-grants/core";
  *
- * using CommonGrants;
+ * using CommonGrants; // exposes the Routes namespace
  *
  * namespace MyRoutes {
  *   alias OpportunityRouter = Routes.Opportunities;
  *
- *   op List is OpportunityRouter.list;
+ *   op list is OpportunityRouter.list;
  * }
- * ```
  */
-namespace Core.Routes;
+namespace CommonGrants.Routes;

package/lib/core/routes/opportunities.tsp

@@ -1,14 +1,13 @@
 import "../models/index.tsp";
 import "../responses/index.tsp";
-import "./utils.tsp";
+import "../pagination.tsp";
 
 // Define the top-level namespace for CommonGrants routes
-namespace Core.Routes;
+namespace CommonGrants.Routes;
 
 // Expose the contents of the Http and Rest namespaces
 // these include the decorators @route, @get, etc.
 using TypeSpec.Http;
-using Core;
 
 /** A re-usable interface for an Opportunities router
  *
@@ -20,7 +19,7 @@ using Core;
  * For more information, see
  * [TypeSpec docs](https://typespec.io/docs/language-basics/interfaces/#templating-interface-operations)
  *
- * @example Using the the default type for the list operation and
+ * @example Using the default type for the list operation and
  * a custom model for the read operation:
  * ```typespec
  * using TypeSpec.Http;
@@ -36,6 +35,10 @@ using Core;
  * ```
  */
 interface Opportunities {
+  // ###############################
+  // List opportunities
+  // ###############################
+
   /** `GET /opportunities/` Get a paginated list of opportunities
    *
    * @template T Type of the paginated response model.
@@ -45,8 +48,12 @@ interface Opportunities {
   @doc("Get a paginated list of opportunities, sorted by `lastModifiedAt` with most recent first.")
   @list
   list<T extends Models.OpportunityBase = Models.OpportunityBase>(
-    ...Utils.PaginatedQuery,
-  ): Responses.Paginated<T> | Responses.Unauthorized;
+    ...Pagination.PaginatedQueryParams,
+  ): Responses.Paginated<T>;
+
+  // ##############################
+  // View an opportunity
+  // ##############################
 
   /** `GET /opportunities/<id>` View opportunity details
    *
@@ -59,5 +66,37 @@ 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
+  // ###############################
+
+  /** `POST /opportunities/search` Search opportunities
+   *
+   * @template T Type of the response model.
+   * Must be an extension of Schemas.OpportunityBase. Default is Schemas.OpportunityBase.
+   */
+  @summary("Search opportunities")
+  @doc("Search for opportunities based on the provided filters")
+  @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
+     * results only include opportunities that match all of the provided filters.
+     */
+    filters?: Models.OppFilters,
+
+    /** The sort order to apply to the results */
+    sorting?: Models.OppSorting,
+
+    /** Pagination instructions for the results */
+    pagination?: Pagination.PaginatedBodyParams,
+  ): Responses.Filtered<T, Models.OppFilters>;
 }

package/lib/core/sorting.tsp

@@ -0,0 +1,75 @@
+import "@typespec/http";
+
+using TypeSpec.Http;
+using TypeSpec.JsonSchema;
+/** Models for sorting
+ *
+ * @example How to use the `Sorting` namespace
+ * ```typespec
+ *
+ * using CommonGrants // Exposes the `Sorting` and `Responses` namespaces
+ * using TypeSpec.Http;
+ *
+ * @route("/foo/")
+ * @get
+ * op list(sorting: Sorting.SortQueryParams): Responses.Sorted<MyModel>;
+ * ```
+ */
+@jsonSchema
+namespace CommonGrants.Sorting;
+
+enum SortOrder {
+  asc,
+  desc,
+}
+
+/** Query parameters for sorting */
+model SortQueryParams {
+  /** The field to sort by */
+  @query
+  @example("lastModifiedAt")
+  sortBy: unknown;
+
+  /** Implementation-defined sort key */
+  @query
+  @example("customField")
+  customSortBy?: string;
+
+  /** The order to sort by */
+  @query
+  @example(SortOrder.asc)
+  sortOrder?: SortOrder;
+}
+
+/** Sorting parameters included in the request body */
+model SortBodyParams {
+  /** The field to sort by */
+  @example("lastModifiedAt")
+  sortBy: unknown;
+
+  /** Implementation-defined sort key */
+  @example("customField")
+  customSortBy?: string;
+
+  /** The order to sort by */
+  @example(SortOrder.asc)
+  sortOrder?: SortOrder;
+}
+
+/** Information about the sort order of the items returned */
+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 used to sort the results, if applicable */
+  @example("customField")
+  customSortBy?: string;
+
+  /** The order in which the results are sorted, e.g. ascending or descending */
+  @example(SortOrder.asc)
+  sortOrder: SortOrder;
+
+  /** Non-fatal errors that occurred during sorting */
+  errors?: string[];
+}

package/lib/core/types.tsp

@@ -1,18 +1,60 @@
-namespace Core.Types;
+using TypeSpec.JsonSchema;
 
-/** A time on a clock, without a timezone, in ISO 8601 format HH:mm:ss */
-@example(isoTime.fromISO("17:00:00"))
-scalar isoTime extends plainTime;
+/** A collection of base data types used throughout the CommonGrants API
+ *
+ * @example How to use the `Types` namespace
+ *
+ * ```typespec
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Types namespace
+ *
+ * model MyModel {
+ *   @example("30a12e5e-5940-4c08-921c-17a8960fcf4b")
+ *   id: Types.uuid;
+ *
+ *   @example(Types.isoDate.fromISO("2025-01-01"))
+ *   keyDate: Types.isoDate;
+ * }
+ * ```
+ */
+@jsonSchema
+namespace CommonGrants.Types;
 
-/** A date on a calendar in ISO 8601 format YYYY-MM-DD */
-@example(isoDate.fromISO("2025-01-01"))
-scalar isoDate extends plainTime;
+// ########################################
+// String types
+// ########################################
 
 /** A universally unique identifier */
 @example("30a12e5e-5940-4c08-921c-17a8960fcf4b")
 @format("uuid")
 scalar uuid extends string;
 
+/** An email address */
+@example("test@example.com")
+@format("email")
+scalar email extends string;
+
+/** An Employer Identification Number (EIN) issued by the IRS */
+@example("12-3456789")
+@pattern("^[0-9]{2}-[0-9]{7}$")
+scalar employerTaxId extends string;
+
+/** A Unique Entity Identifier (UEI) issued by SAM.gov */
+@example("12ABC34DEF56")
+@pattern("^[A-z0-9]{12}$")
+scalar samUEI extends string;
+
+/** A Data Universal Numbering System (DUNS) number */
+@example("123456789")
+@example("12-345-6789")
+@example("123456789-1234")
+scalar duns extends string;
+
+// ########################################
+// Numeric types
+// ########################################
+
 /** A decimal number (with variable scale) encoded as a string, to avoid floating point issues */
 @pattern(
   "^-?[0-9]+\\.?[0-9]*$",
@@ -22,3 +64,20 @@ scalar uuid extends string;
 @example("100.5", #{ title: "Scale 1" })
 @example("-100.5", #{ title: "Negative, scale 2" })
 scalar decimalString extends string;
+
+// ########################################
+// Date types
+// ########################################
+
+/** A time on a clock, without a timezone, in ISO 8601 format HH:mm:ss */
+@example(isoTime.fromISO("17:00:00"))
+scalar isoTime extends plainTime;
+
+/** A date on a calendar in ISO 8601 format YYYY-MM-DD */
+@example(isoDate.fromISO("2025-01-01"))
+scalar isoDate extends plainDate;
+
+/** A calendar year */
+@example("2025")
+@pattern("^[0-9]{4}$")
+scalar calendarYear extends string;

package/lib/main.tsp

@@ -3,92 +3,7 @@
 // https://typespec.io/docs/extending-typespec/basics/#h-add-your-main-typespec-file
 import "../dist/src/index.js";
 
-// Import items from the Core namespace to make them available outside the package
 import "./core/index.tsp";
 import "./api.tsp";
 
 namespace CommonGrants;
-
-/** Base data types, e.g. `uuid` and `isoDate`, used to build more complex fields and models
- *
- * @example How to use the `Types` namespace
- *
- * ```tsp
- * import "@common-grants/core";
- *
- * using CommonGrants; // exposes the Types namespace
- *
- * model MyModel {
- *   id: Types.uuid;
- *   createdAt: Types.isoDate;
- * }
- * ```
- */
-alias Types = Core.Types;
-
-/** A standard set of fields, e.g. `money` that can be reused across models
- *
- * @example How to use the `Fields` namespace
- *
- * ```tsp
- * import "@common-grants/core";
- *
- * using CommonGrants; // exposes the Fields namespace
- *
- * model MyModel {
- *   amount: Fields.money;
- * }
- * ```
- */
-alias Fields = Core.Fields;
-
-/** A standardized set of response schemas for CommonGrants API routes
- *
- * @example How to use the `Responses` namespace
- *
- * ```tsp
- * import "@typespec/http";
- * import "@common-grants/core";
- *
- * using CommonGrants; // exposes the Responses namespace
- * using TypeSpec.Http;
- *
- * @route("/pets")
- * namespace Pets {
- *   @get
- *   getPets(): Responses.Ok<Pet> | Responses.Unauthorized;
- * }
- * ```
- */
-alias Responses = Core.Responses;
-
-/** A collection of models for the CommonGrants API
- *
- * @example How to use the `Models` namespace
- *
- * ```tsp
- * import "@common-grants/core";
- *
- * using CommonGrants; // exposes the Models namespace
- *
- * model MyModel extends Models.OpportunityBase {}
- * ```
- */
-alias Models = Core.Models;
-
-/** A series of routing interfaces for CommonGrants API endpoints
- *
- * @example How to use the `Routes` namespace
- *
- * ```tsp
- * import "@common-grants/core";
- *
- * using CommonGrants; // exposes the Routes namespace
- *
- * namespace MyRoutes {
- *   alias OpportunityRouter = Routes.Opportunities;
- *
- *   op List is OpportunityRouter.list;
- * }
- */
-alias Routes = Core.Routes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common-grants/core",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",
@@ -21,6 +21,15 @@
     "lib/**/*.tsp",
     "!src/**/*.test.*"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HHS/simpler-grants-protocol.git",
+    "directory": "lib/core"
+  },
+  "bugs": {
+    "url": "https://github.com/HHS/simpler-grants-protocol/issues"
+  },
+  "homepage": "https://github.com/HHS/simpler-grants-protocol/tree/main/lib/core/#readme",
   "scripts": {
     "clean": "rimraf dist tsp-output",
     "build": "tsc -p .",
@@ -31,10 +40,7 @@
     "format": "prettier --write . && tsp format lib",
     "check:lint": "eslint",
     "check:format": "prettier --check . && tsp format lib --check",
-    "checks": "npm run check:lint && npm run check:format",
-    "docs:build": "npx @redocly/cli build-docs tsp-output/@typespec/openapi3/openapi.yaml --output ./dist/redocly.html",
-    "docs:preview": "open ./dist/redocly.html",
-    "docs": "npm run typespec && npm run docs:build && npm run docs:preview"
+    "checks": "npm run check:lint && npm run check:format"
   },
   "keywords": [
     "typespec",
@@ -45,11 +51,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",

package/lib/core/routes/utils.tsp

@@ -1,19 +0,0 @@
-import "@typespec/http";
-
-using TypeSpec.Http;
-
-/** Utility models and functions for API routes */
-namespace Core.Routes.Utils;
-
-/** A set of query parameters for paginated routes */
-model PaginatedQuery {
-  /** The page to return */
-  @query
-  @pageIndex
-  page?: int32 = 1;
-
-  /** The number of items to return per page */
-  @query
-  @pageSize
-  pageSize?: int32 = 100;
-}