@common-grants/core 0.1.0-alpha.10

package/lib/core/filters/string.tsp

@@ -0,0 +1,31 @@
+import "./base.tsp";
+
+namespace CommonGrants.Filters;
+
+// ############################################################################
+// String comparison filter
+// ############################################################################
+
+/** A filter that applies a comparison to a string value */
+model StringComparisonFilter {
+  /** The operator to apply to the filter value */
+  operator: EquivalenceOperators | StringOperators;
+
+  /** The value to use for the filter operation */
+  @example("value")
+  value: string;
+}
+
+// ############################################################################
+// String array filter
+// ############################################################################
+
+/** A filter that applies a filter to an array of strings */
+model StringArrayFilter {
+  /** The operator to apply to the filter value */
+  operator: ArrayOperators;
+
+  /** The value to use for the filter operation */
+  @example(#["value1", "value2"])
+  value: Array<string>;
+}

package/lib/core/index.tsp

@@ -0,0 +1,8 @@
+import "./types.tsp";
+import "./fields/index.tsp";
+import "./models/index.tsp";
+import "./routes/index.tsp";
+import "./responses/index.tsp";
+
+/** An internal namespace for the `@common-grants/core` package */
+namespace CommonGrants;

package/lib/core/models/index.tsp

@@ -0,0 +1,22 @@
+import "@typespec/json-schema";
+
+// Import individual schemas to provide a consistent interface
+// and make them available throughout the namespace
+import "./opportunity/index.tsp";
+
+using TypeSpec.JsonSchema;
+
+/** A collection of models for the CommonGrants API
+ *
+ * @example How to use the `Models` namespace
+ *
+ * ```typespec
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Models namespace
+ *
+ * model MyModel extends Models.OpportunityBase {}
+ * ```
+ */
+@jsonSchema // and emit these Schemas.as JSON schemas
+namespace CommonGrants.Models;

package/lib/core/models/opportunity/base.tsp

@@ -0,0 +1,72 @@
+import "./status.tsp";
+import "./funding.tsp";
+import "./timeline.tsp";
+import "../../fields/index.tsp";
+import "../../types.tsp";
+
+/** Namespace for Core that are specific to funding opportunities */
+namespace CommonGrants.Models;
+
+using CommonGrants.Fields;
+using CommonGrants.Types;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** The base model for a funding opportunity.
+ *
+ * It supports customization by extending the `customFields` property.
+ *
+ * @example How to declare a new Opportunity model with custom fields
+ *
+ * ```typespec
+ * using CommonGrants.Fields;
+ * using CommonGrants.Models;
+ *
+ * model Agency extends CustomField {
+ *   type: CustomFieldType.string;
+ *
+ *   @example("Department of Transportation")
+ *   value: string;
+ * }
+ *
+ * model NewFields extends CustomFieldMap {
+ *   agency: Agency;
+ * }
+ *
+ * model CustomOpportunity extends OpportunityBase {
+ *   customFields: NewFields;
+ * }
+ * ```
+ */
+@doc("A funding opportunity") // Overrides internal docstrings when emitting OpenAPI
+model OpportunityBase {
+  /** Globally unique id for the opportunity */
+  @visibility(Lifecycle.Read)
+  id: uuid;
+
+  /** Title or name of the funding opportunity */
+  title: string;
+
+  /** Status of the opportunity */
+  status: OppStatus;
+
+  /** Description of the opportunity's purpose and scope */
+  description: string;
+
+  /** Details about the funding available */
+  funding: OppFunding;
+
+  /** Key dates for the opportunity, such as when the application opens and closes */
+  keyDates: OppTimeline;
+
+  /** URL for the original source of the opportunity */
+  source?: url;
+
+  /** Additional custom fields specific to this opportunity */
+  customFields?: Record<CustomField>;
+
+  // Spreads the fields from the Metadata model into the Opportunity model
+  ...SystemMetadata;
+}

package/lib/core/models/opportunity/funding.tsp

@@ -0,0 +1,71 @@
+import "../index.tsp";
+import "../../fields/index.tsp";
+
+namespace CommonGrants.Models;
+
+using CommonGrants.Fields;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** Details about the funding available for this opportunity */
+@example(
+  Examples.Funding.awardRange,
+  #{ title: "Award range but no total limit" }
+)
+@example(
+  Examples.Funding.onlyLimit,
+  #{ title: "Total funding limit but no award range" }
+)
+@example(Examples.Funding.allFields, #{ title: "All fields defined" })
+model OppFunding {
+  /** Total amount of funding available for this opportunity */
+  totalAmountAvailable?: Money;
+
+  /** Minimum amount of funding granted per award */
+  minAwardAmount?: Money;
+
+  /** Maximum amount of funding granted per award */
+  maxAwardAmount?: Money;
+
+  /** Minimum number of awards granted */
+  minAwardCount?: integer;
+
+  /** Maximum number of awards granted */
+  maxAwardCount?: integer;
+
+  /** Estimated number of awards that will be granted */
+  estimatedAwardCount?: integer;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+/** Examples of the OppFunding model */
+namespace Examples.Funding {
+  /** A FundingDetails example in which all of the fields are defined */
+  const allFields = #{
+    totalAmountAvailable: #{ amount: "1000000.00", currency: "USD" },
+    minAwardAmount: #{ amount: "10000.00", currency: "USD" },
+    maxAwardAmount: #{ amount: "50000.00", currency: "USD" },
+    minAwardCount: 5,
+    maxAwardCount: 20,
+    estimatedAwardCount: 10,
+  };
+
+  /** A FundingDetails example that has an award range but no total limit */
+  const awardRange = #{
+    minAwardAmount: #{ amount: "10000.00", currency: "USD" },
+    maxAwardAmount: #{ amount: "50000.00", currency: "USD" },
+    minAwardCount: 5,
+    maxAwardCount: 20,
+  };
+
+  /** A FundingDetails example that has a total limit but no award range */
+  const onlyLimit = #{
+    totalAmountAvailable: #{ amount: "1000000.00", currency: "USD" },
+    estimatedAwardCount: 10,
+  };
+}

package/lib/core/models/opportunity/index.tsp

@@ -0,0 +1,7 @@
+import "./status.tsp";
+import "./funding.tsp";
+import "./timeline.tsp";
+import "./base.tsp";
+import "./search.tsp";
+
+namespace CommonGrants.Models;

package/lib/core/models/opportunity/search.tsp

@@ -0,0 +1,102 @@
+import "../../filters/index.tsp";
+import "../../sorting.tsp";
+
+namespace CommonGrants.Models;
+
+// ############################################################################
+// Filter models
+// ############################################################################
+
+/** Filters to apply when searching for opportunities */
+model OppFilters {
+  /** The default filters to apply to the search */
+  ...OppDefaultFilters;
+
+  /** Additional implementation-defined filters to apply to the search */
+  customFilters?: Record<Filters.DefaultFilter>;
+}
+
+/** The standard set of filters supported for opportunity searches */
+model OppDefaultFilters extends Record<Filters.DefaultFilter> {
+  /** `status.value` matches one of the following values */
+  @example(#{
+    operator: Filters.ArrayOperators.in,
+    value: #["forecasted", "open"],
+  })
+  status?: Filters.StringArrayFilter;
+
+  /** `keyDates.closeDate` is between the given range */
+  @example(#{
+    operator: Filters.RangeOperators.between,
+    value: #{
+      min: Types.isoDate.fromISO("2021-01-01"),
+      max: Types.isoDate.fromISO("2021-01-02"),
+    },
+  })
+  closeDateRange?: Filters.DateRangeFilter;
+
+  /** `funding.totalAmountAvailable` is between the given range
+   *
+   * Funding amounts that are denominated in a different currency will
+   * be excluded from the search.
+   */
+  @example(#{
+    operator: Filters.RangeOperators.between,
+    value: #{
+      min: #{ amount: "1000000", currency: "USD" },
+      max: #{ amount: "2000000", currency: "USD" },
+    },
+  })
+  totalFundingAvailableRange?: Filters.MoneyRangeFilter;
+
+  /** `funding.minAwardAmount` is between the given range
+   *
+   * Funding amounts that are denominated in a different currency will
+   * be excluded from the search.
+   */
+  @example(#{
+    operator: Filters.RangeOperators.between,
+    value: #{
+      min: #{ amount: "1000000", currency: "USD" },
+      max: #{ amount: "2000000", currency: "USD" },
+    },
+  })
+  minAwardAmountRange?: Filters.MoneyRangeFilter;
+
+  /** `funding.maxAwardAmount` is between the given range.
+   *
+   * Funding amounts that are denominated in a different currency will
+   * be excluded from the search.
+   */
+  @example(#{
+    operator: Filters.RangeOperators.between,
+    value: #{
+      min: #{ amount: "1000000", currency: "USD" },
+      max: #{ amount: "2000000", currency: "USD" },
+    },
+  })
+  maxAwardAmountRange?: Filters.MoneyRangeFilter;
+}
+
+// ############################################################################
+// Sorting models
+// ############################################################################
+
+enum OppSortBy {
+  lastModifiedAt,
+  createdAt,
+  title,
+  status: "status.value",
+  closeDate: "keyDates.closeDate",
+  maxAwardAmount: "funding.maxAwardAmount",
+  minAwardAmount: "funding.minAwardAmount",
+  totalFundingAvailable: "funding.totalAmountAvailable",
+  estimatedAwardCount: "funding.estimatedAwardCount",
+  custom,
+}
+
+model OppSorting extends Sorting.SortBodyParams {
+  /** The field to sort by */
+  @example(OppSortBy.lastModifiedAt)
+  sortBy: OppSortBy;
+}

package/lib/core/models/opportunity/status.tsp

@@ -0,0 +1,52 @@
+import "@typespec/json-schema";
+import "@typespec/openapi3";
+
+namespace CommonGrants.Models;
+
+// ########################################
+// Opportunity status options
+// ########################################
+
+/** The set of values accepted for opportunity status */
+enum OppStatusOptions {
+  forecasted,
+  open,
+  closed,
+  custom,
+}
+
+// ########################################
+// Opportunity status model
+// ########################################
+
+/** The status of the opportunity */
+@example(Examples.OppStatus.custom)
+@example(Examples.OppStatus.default)
+model OppStatus {
+  /** The status value, from a predefined set of options */
+  value: OppStatusOptions;
+
+  /** A custom status value */
+  customValue?: string;
+
+  /** A human-readable description of the status */
+  description?: string;
+}
+
+// ########################################
+// Opportunity status model examples
+// ########################################
+
+/** Examples of the OppStatus model */
+namespace Examples.OppStatus {
+  const default = #{
+    value: OppStatusOptions.open,
+    description: "The opportunity is currently accepting applications",
+  };
+
+  const custom = #{
+    value: OppStatusOptions.custom,
+    customValue: "archived",
+    description: "The opportunity is archived and shouldn't appear in search results",
+  };
+}

package/lib/core/models/opportunity/timeline.tsp

@@ -0,0 +1,46 @@
+import "../../fields/index.tsp";
+import "../../types.tsp";
+
+namespace CommonGrants.Models;
+
+using CommonGrants.Fields;
+using CommonGrants.Types;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** Key dates in the opportunity's timeline, such as when the application opens and closes */
+@example(Examples.Timeline.opportunity)
+model OppTimeline {
+  /** The date (and time) at which the opportunity begins accepting applications */
+  appOpens?: Event;
+
+  /** The final deadline for submitting applications */
+  appDeadline?: Event;
+
+  /** An optional map of other key dates in the opportunity timeline
+   *
+   * Examples might include a deadline for questions, anticipated award date, etc.
+   */
+  otherDates?: Record<Event>;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+/** Examples of the OppTimeline model */
+namespace Examples.Timeline {
+  const opportunity = #{
+    appOpens: Fields.Examples.Event.openDate,
+    appDeadline: Fields.Examples.Event.deadline,
+    otherDates: #{
+      anticipatedAward: #{
+        name: "Anticipated award date",
+        date: isoDate.fromISO("2025-03-15"),
+        description: "When we expect to announce awards for this opportunity.",
+      },
+    },
+  };
+}

package/lib/core/pagination.tsp

@@ -0,0 +1,55 @@
+import "@typespec/http";
+
+using TypeSpec.Http;
+
+/** Models and utilities for pagination */
+namespace CommonGrants.Pagination;
+
+/** Query parameters for paginated routes */
+model PaginatedQueryParams {
+  /** The page to return */
+  @query
+  @pageIndex
+  @minValue(1)
+  page?: int32 = 1;
+
+  /** The number of items to return per page */
+  @query
+  @pageSize
+  @minValue(1)
+  pageSize?: int32 = 100;
+}
+
+/** Body parameters for paginated routes */
+model PaginatedBodyParams {
+  /** The page to return */
+  @pageIndex
+  @minValue(1)
+  page?: int32 = 1;
+
+  /** The number of items to return per page */
+  @pageSize
+  @minValue(1)
+  pageSize?: int32 = 100;
+}
+
+/** Details about the paginated results */
+model PaginationInfo {
+  /** Current page number (indexing starts at 1) */
+  @example(1)
+  @minValue(1)
+  page: int32;
+
+  /** Number of items per page */
+  @example(20)
+  @minValue(1)
+  pageSize: integer;
+
+  /** Total number of items across all pages */
+  @example(100)
+  totalItems?: integer;
+
+  /** Total number of pages */
+  @example(5)
+  totalPages?: integer;
+}

package/lib/core/responses/error.tsp

@@ -0,0 +1,30 @@
+import "@typespec/http";
+
+namespace CommonGrants.Responses;
+
+/** A standard error response schema, used to create custom error responses
+ *
+ * @example - How to use this model to create custom error response schemas
+ *
+ * ```
+ * import "@typespec/http"
+ *
+ * alias Unauthorized = Error & Http.UnauthorizedResponse
+ * ```
+ */
+@error
+@doc("A non-2xx response schema")
+model Error {
+  @example(400)
+  status: int32;
+
+  /** Human-readable error message */
+  @example("Error")
+  message: string;
+
+  /** List of errors */
+  errors: Array<unknown>;
+}
+
+alias Unauthorized = Error & Http.UnauthorizedResponse;
+alias NotFound = Error & Http.NotFoundResponse;

package/lib/core/responses/index.tsp

@@ -0,0 +1,24 @@
+import "@typespec/http";
+
+import "./error.tsp";
+import "./success.tsp";
+
+/** A standardized set of response schemas for CommonGrants API routes
+ *
+ * @example How to use the `Responses` namespace
+ *
+ * ```typespec
+ * import "@typespec/http";
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Responses namespace
+ * using TypeSpec.Http;
+ *
+ * @route("/pets")
+ * namespace Pets {
+ *   @get
+ *   op getPets(): Responses.Ok<Pet> | Responses.Unauthorized;
+ * }
+ * ```
+ */
+namespace CommonGrants.Responses;

package/lib/core/responses/success.tsp

@@ -0,0 +1,141 @@
+import "../pagination.tsp";
+import "../sorting.tsp";
+import "@typespec/http";
+
+namespace CommonGrants.Responses;
+
+// ############################################################################
+// Default success response
+// ############################################################################
+
+model Success {
+  @example(200)
+  status: int32;
+
+  @example("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;
+ *   description: string;
+ * }
+ *
+ * // Pass that model to the `Ok` template
+ * alias CustomModel200 = Responses.Ok<CustomModel>;
+ * ```
+ */
+@doc("A 200 response with data")
+model Ok<T> extends Success {
+  // Inherit the 200 status code
+  ...Http.OkResponse;
+
+  /** Response data */
+  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;
+ *   description: string;
+ * }
+ *
+ * // Pass that model to the `Ok` template
+ * alias CustomModelResponse = Responses.Paginated<CustomModel>;
+ * ```
+ */
+@doc("A 200 response with a paginated list of items")
+model Paginated<T> extends Success {
+  // Inherit the 200 status code
+  ...Http.OkResponse;
+
+  /** Items from the current page */
+  @pageItems
+  items: T[];
+
+  /** Details about the paginated results */
+  paginationInfo: Pagination.PaginationInfo;
+}
+
+// ############################################################################
+// 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.SortInfo;
+}
+
+// ############################################################################
+// 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: FilterT;
+}

package/lib/core/routes/index.tsp

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