@common-grants/core 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,132 @@
+# CommonGrants core library
+
+Code for the CommonGrants core specification library, written in TypeSpec. This library is designed to be imported and extended by individual implementations of the CommonGrants protocol.
+
+## 🚀 Quickstart
+
+### Install the library
+
+```bash
+npm install @common-grants/core
+```
+
+### Project setup
+
+A basic project structure that uses the library might look like this:
+
+```
+.
+├── models.tsp      # Extends @common-grants/core models with custom fields
+├── routes.tsp      # Overrides @common-grants/core routes to use the custom models
+├── main.tsp        # Defines an API service that uses the custom models and routes
+|
+├── tsp-output/     # Directory that stores the output of `tsp compile`, often .gitignored
+|
+├── package.json    # Manages dependencies, commands, and library metadata
+└── tspconfig.yaml  # Manages TypeSpec configuration, including emitters
+```
+
+### Define custom fields
+
+The Opportunity model is templated to support custom fields. First define your custom fields by extending the `CustomField` model:
+
+```typespec
+// models.tsp
+
+import "@common-grants/core"; // Import the base specification library
+
+// Allows us to use models and fields defined in the core library without
+// prefixing each item with `CommonGrants.Models` or `CommonGrants.Fields`
+using CommonGrants.Models;
+using CommonGrants.Fields;
+
+namespace CustomAPI.CustomModels;
+
+// Define a custom field
+model Agency extends CustomField {
+  name: "Agency";
+  type: CustomFieldType.string;
+
+  @example("Department of Transportation")
+  value: string;
+
+  description: "The agency responsible for this opportunity";
+}
+
+// Extend the `OpportunityBase` model to create a new `CustomOpportunity` model
+// that includes the new `Agency` field in its `customFields` property
+model CustomOpportunity extends OpportunityBase {
+  customFields: {
+    agency: Agency;
+  };
+}
+```
+
+### Override default routes
+
+The router interfaces are templated to support your custom models. Override them like this:
+
+```typespec
+// routes.tsp
+
+import "@common-grants/core";
+import "./models.tsp"; // Import the custom field and model from above
+
+using CommonGrants.Routes;
+using TypeSpec.Http;
+
+@tag("Search")
+@route("/common-grants/opportunities")
+namespace CustomAPI.CustomRoutes {
+  alias OpportunitiesRouter = Opportunities;
+
+  // Use the default model for list but custom model for read and search
+  op list is OpportunitiesRouter.list;
+  op read is OpportunitiesRouter.read<CustomModels.CustomOpportunity>;
+  op search is OpportunitiesRouter.search<CustomModels.CustomOpportunity>;
+}
+```
+
+### Define an API service
+
+Next, use these updated routes to define an API service:
+
+```typespec
+// main.tsp
+
+import "@typespec/http";
+
+import "./routes.tsp"; // Import the routes from above
+
+using TypeSpec.Http;
+
+/** Description of your API goes here */
+@service({
+  title: "Custom API",
+})
+namespace CustomAPI;
+```
+
+### Generate the OpenAPI spec
+
+Generate an OpenAPI specification from your `main.tsp` file using either the CLI:
+
+```bash
+npx tsp compile main.tsp --emit "@typespec/openapi3"
+```
+
+Or specify the emitter in `tspconfig.yaml`:
+
+```yaml
+# tspconfig.yaml
+emitters:
+  - "@typespec/openapi3"
+```
+
+Both strategies will generate an OpenAPI specification in the `tsp-output/` directory.
+
+### Further reading
+
+- See the [TypeSpec documentation](https://typespec.org/docs/getting-started/overview) for more information on how to use TypeSpec.
+- See the [CommonGrants docs](https://hhs.github.io/simpler-grants-protocol/) to learn more about the CommonGrants protocol.
+- See the [CommonGrants CLI](https://www.npmjs.com/package/@common-grants/cli) for more developer tools related to the CommonGrants protocol.

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { $lib } from "./lib.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -0,0 +1,3 @@
+// Re-export $lib so the compiler can access it and register your library correctly
+export { $lib } from "./lib.js";
+//# sourceMappingURL=index.js.map

package/dist/src/lib.d.ts

@@ -0,0 +1,13 @@
+export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}, Record<string, any>, never>;
+export declare const reportDiagnostic: <C extends string | number, M extends keyof {
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}[C]>(program: import("@typespec/compiler").Program, diag: import("@typespec/compiler").DiagnosticReport<{
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}, C, M>) => void, createDiagnostic: <C extends string | number, M extends keyof {
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}[C]>(diag: import("@typespec/compiler").DiagnosticReport<{
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}, C, M>) => import("@typespec/compiler").Diagnostic;
+//# sourceMappingURL=lib.d.ts.map

package/dist/src/lib.js

@@ -0,0 +1,10 @@
+import { createTypeSpecLibrary } from "@typespec/compiler";
+export const $lib = createTypeSpecLibrary({
+    name: "@common-grants/core",
+    diagnostics: {
+    // We'll add diagnostics later if needed
+    },
+});
+// Optional but convenient, these are meant to be used locally in your library
+export const { reportDiagnostic, createDiagnostic } = $lib;
+//# sourceMappingURL=lib.js.map

package/lib/api.tsp

@@ -0,0 +1,32 @@
+// Import Schemas.and Routes to make them available outside the package
+import "./core/index.tsp";
+import "@typespec/http";
+import "@typespec/openapi";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+
+/** The base OpenAPI specification for a CommonGrants API
+ *
+ * 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",
+})
+namespace CommonGrants.API;
+
+@tag("Opportunities")
+@route("/common-grants/opportunities")
+namespace Opportunities {
+  alias Router = Routes.Opportunities;
+
+  @tag("required")
+  op list is Router.list;
+
+  @tag("required")
+  op read is Router.read;
+
+  @tag("optional")
+  op search is Router.search;
+}

package/lib/core/fields/custom-field.tsp

@@ -0,0 +1,85 @@
+namespace CommonGrants.Fields;
+
+// ########################################
+// Field types definition
+// ########################################
+
+/** The set of JSON schema types supported by a custom field */
+enum CustomFieldType {
+  string,
+  number,
+  boolean,
+  object,
+  array,
+}
+
+// ########################################
+// Model definition
+// ########################################
+
+/** Model for defining custom fields that are specific to a given implementation.
+ *
+ * @example How to define a custom field using this model
+ *
+ * ```typespec
+ * model Agency extends CustomField {
+ *   name: "agency";
+ *
+ *   type: CustomFieldType.string;
+ *
+ *   @example("Department of Transportation")
+ *   value: string;
+ *
+ *   description?: "The agency responsible for managing this opportunity";
+ * }
+ * ```
+ */
+@example(
+  Examples.CustomField.programArea,
+  #{ title: "String field for program area" }
+)
+@example(
+  Examples.CustomField.eligibilityTypes,
+  #{ title: "Array field for eligibility types" }
+)
+@doc("A custom field on a model") // Overrides internal docstrings when emitting OpenAPI
+model CustomField {
+  /** Name of the custom field */
+  name: string;
+
+  /** The JSON schema type to use when de-serializing the `value` field */
+  type: CustomFieldType;
+
+  /** Link to the full JSON schema for this custom field */
+  schema?: url;
+
+  /** Value of the custom field */
+  value: unknown;
+
+  /** Description of the custom field's purpose */
+  description?: string;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+/** Examples of the CustomField model */
+namespace Examples.CustomField {
+  /** An example of a string custom field */
+  const programArea = #{
+    name: "programArea",
+    type: CustomFieldType.string,
+    value: "Healthcare Innovation",
+    description: "Primary focus area of the grant program",
+    schema: "https://example.com/program-areas.json",
+  };
+
+  /** An example of an array custom field */
+  const eligibilityTypes = #{
+    name: "eligibilityType",
+    type: CustomFieldType.array,
+    value: #["nonprofit", "academic"],
+    description: "Types of eligible organizations",
+  };
+}

package/lib/core/fields/event.tsp

@@ -0,0 +1,47 @@
+import "../types.tsp";
+
+namespace CommonGrants.Fields;
+
+using CommonGrants.Types;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** Description of an event that has a date (and possible time) associated with it */
+@example(Examples.Event.deadline, #{ title: "Application deadline with time" })
+@example(Examples.Event.openDate, #{ title: "Opening date without time" })
+model Event {
+  /** Human-readable name of the event (e.g., 'Application posted', 'Question deadline') */
+  name: string;
+
+  /** Date of the event in in ISO 8601 format: YYYY-MM-DD */
+  date: isoDate;
+
+  /** Time of the event in ISO 8601 format: HH:MM:SS */
+  time?: isoTime;
+
+  /** Description of what this event represents */
+  description?: string;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+namespace Examples.Event {
+  /** An example of a deadline event with a specific time */
+  const deadline = #{
+    name: "Application Deadline",
+    date: isoDate.fromISO("2024-12-31"),
+    time: isoTime.fromISO("17:00:00"),
+    description: "Final submission deadline for all grant applications",
+  };
+
+  /** An example of an opening date without a specific time */
+  const openDate = #{
+    name: "Open Date",
+    date: isoDate.fromISO("2024-01-15"),
+    description: "Applications begin being accepted",
+  };
+}

package/lib/core/fields/index.tsp

@@ -0,0 +1,20 @@
+import "./custom-field.tsp";
+import "./metadata.tsp";
+import "./money.tsp";
+import "./event.tsp";
+
+/** A standard set of fields, e.g. `money` that can be reused across models
+ *
+ * @example How to use the `Fields` namespace
+ *
+ * ```typespec
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Fields namespace
+ *
+ * model MyModel {
+ *   amount: Fields.money;
+ * }
+ * ```
+ */
+namespace CommonGrants.Fields;

package/lib/core/fields/metadata.tsp

@@ -0,0 +1,42 @@
+namespace CommonGrants.Fields;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** Standard system-level metadata about a given record.
+ *
+ * @example How to spread the SystemMetadata props into another record
+ *
+ * ```typespec
+ * model Opportunity {
+ *   id: uuid;
+ *   title: string;
+ *
+ *   // Includes SystemMetadata props in the root of the Opportunity model
+ *   ...SystemMetadata;
+ * }
+ * ```
+ * */
+@example(Examples.Metadata.system)
+model SystemMetadata {
+  /** The timestamp (in UTC) at which the record was created. */
+  @visibility(Lifecycle.Read)
+  createdAt: utcDateTime;
+
+  /** The timestamp (in UTC) at which the record was last modified. */
+  @visibility(Lifecycle.Read)
+  lastModifiedAt: utcDateTime;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+/** Examples of the SystemMetadata model */
+namespace Examples.Metadata {
+  const system = #{
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
+  };
+}

package/lib/core/fields/money.tsp

@@ -0,0 +1,43 @@
+import "../types.tsp";
+
+namespace CommonGrants.Fields;
+
+using CommonGrants.Types;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** A monetary amount and the currency in which its denominated */
+@example(Examples.Money.usdWithCents, #{ title: "US dollars and cents" })
+@example(
+  Examples.Money.euroWithoutCents,
+  #{ title: "Euros displayed without cents" }
+)
+@example(
+  Examples.Money.usdNegative,
+  #{ title: "A negative amount of US dollars and cents" }
+)
+model Money {
+  /** The amount of money */
+  amount: decimalString;
+
+  /** The ISO 4217 currency code in which the amount is denominated */
+  currency: string;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+/** Examples of the Money model */
+namespace Examples.Money {
+  /** An example of a positive USD amount with cents */
+  const usdWithCents = #{ amount: "10000.50", currency: "USD" };
+
+  /** An example of a positive EUR amount without cents */
+  const euroWithoutCents = #{ amount: "5000", currency: "EUR" };
+
+  /** An example of a negative USD amount in accounting format */
+  const usdNegative = #{ amount: "-50.50", currency: "USD" };
+}

package/lib/core/filters/base.tsp

@@ -0,0 +1,82 @@
+namespace CommonGrants.Filters;
+
+// ############################################################################
+// Filter operators
+// ############################################################################
+
+/** Operators that filter a field based on an exact match to a value */
+enum EquivalenceOperators {
+  /** Equal to a value */
+  eq,
+
+  /** Not equal to a value */
+  neq,
+}
+
+/** Operators that filter a field based on a comparison to a value */
+enum ComparisonOperators {
+  /** Greater than a value */
+  gt,
+
+  /** Greater than or equal to a value */
+  gte,
+
+  /** Less than a value */
+  lt,
+
+  /** Less than or equal to a value */
+  lte,
+}
+
+/** Operators that filter a field based on an array of values */
+enum ArrayOperators {
+  /** In an array of values */
+  in,
+
+  /** Not in an array of values */
+  not_in,
+}
+
+/** Operators that filter a field based on a string value */
+enum StringOperators {
+  /** Like */
+  like,
+
+  /** Not like */
+  not_like,
+}
+
+/** Operators that filter a field based on a range of values */
+enum RangeOperators {
+  /** Between a range of values */
+  between,
+
+  /** Outside a range of values */
+  outside,
+}
+
+enum AllOperators {
+  ...EquivalenceOperators,
+  ...ComparisonOperators,
+  ...ArrayOperators,
+  ...RangeOperators,
+  ...StringOperators,
+}
+
+// ############################################################################
+// Filter model
+// ############################################################################
+
+/** A base filter model that can be used to create more specific filter models */
+model DefaultFilter {
+  /** The operator to apply to the filter value */
+  operator:
+    | ComparisonOperators
+    | ArrayOperators
+    | StringOperators
+    | RangeOperators
+    | AllOperators;
+
+  /** The value to use for the filter operation */
+  value: unknown;
+}

package/lib/core/filters/date.tsp

@@ -0,0 +1,38 @@
+import "./base.tsp";
+import "../types.tsp";
+
+namespace CommonGrants.Filters;
+
+// ############################################################################
+// Date comparison filter
+// ############################################################################
+
+/** Filters by comparing a field to a date value */
+model DateComparisonFilter {
+  /** The operator to apply to the filter value */
+  operator: ComparisonOperators;
+
+  /** The value to use for the filter operation */
+  @example(Types.isoDate.fromISO("2021-01-01"))
+  value: Types.isoDate | utcDateTime | offsetDateTime;
+}
+
+// ############################################################################
+// Date range filter
+// ############################################################################
+
+/** Filters by comparing a field to a range of date values */
+model DateRangeFilter {
+  /** The operator to apply to the filter value */
+  operator: RangeOperators;
+
+  /** The value to use for the filter operation */
+  @example(#{
+    min: Types.isoDate.fromISO("2021-01-01"),
+    max: Types.isoDate.fromISO("2021-01-02"),
+  })
+  value: {
+    min: Types.isoDate | utcDateTime | offsetDateTime;
+    max: Types.isoDate | utcDateTime | offsetDateTime;
+  };
+}

package/lib/core/filters/index.tsp

@@ -0,0 +1,37 @@
+import "./base.tsp";
+import "./date.tsp";
+import "./numeric.tsp";
+import "./money.tsp";
+import "./string.tsp";
+
+/** A standard set of filters, e.g. `StringArrayFilter`, that can be reused across models
+ *
+ * @example How to use the `Filters` namespace
+ *
+ * ```typespec
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Filters namespace
+ *
+ * model MyFilters extends Record<Filters.DefaultFilter> {
+ *   @example(#{
+ *     operator: Filters.FilterOperators.in,
+ *     value: #["foo", "bar", "baz"],
+ *   })
+ *   stringField: Filters.StringArrayFilter;
+ *
+ *   @example(#{ operator: Filters.FilterOperators.gt, value: 10 })
+ *   numberField: Filters.NumberComparisonFilter;
+ *
+ *   @example(#{
+ *     operator: Filters.FilterOperators.between,
+ *     value: #{
+ *       min: Types.isoDate.fromISO("2021-01-01"),
+ *       max: Types.isoDate.fromISO("2021-01-02"),
+ *     },
+ *   })
+ *   dateField: Filters.DateRangeFilter;
+ * }
+ * ```
+ */
+namespace CommonGrants.Filters;

package/lib/core/filters/money.tsp

@@ -0,0 +1,38 @@
+import "./base.tsp";
+import "../fields/index.tsp";
+
+namespace CommonGrants.Filters;
+
+// ############################################################################
+// Money comparison filter
+// ############################################################################
+
+/** Filters by comparing a field to a monetary value */
+model MoneyComparisonFilter {
+  /** The operator to apply to the filter value */
+  operator: ComparisonOperators;
+
+  /** The value to use for the filter operation */
+  @example(#{ amount: "1000", currency: "USD" })
+  value: Fields.Money;
+}
+
+// ############################################################################
+// Date range filter
+// ############################################################################
+
+/** Filters by comparing a field to a range of monetary values */
+model MoneyRangeFilter {
+  /** The operator to apply to the filter value */
+  operator: RangeOperators;
+
+  /** The value to use for the filter operation */
+  @example(#{
+    min: #{ amount: "1000", currency: "USD" },
+    max: #{ amount: "10000", currency: "USD" },
+  })
+  value: {
+    min: Fields.Money;
+    max: Fields.Money;
+  };
+}

package/lib/core/filters/numeric.tsp

@@ -0,0 +1,50 @@
+import "../types.tsp";
+import "./base.tsp";
+import "../fields/index.tsp";
+
+namespace CommonGrants.Filters;
+
+// ############################################################################
+// Number comparison filter
+// ############################################################################
+
+/** Filters by comparing a field to a numeric value */
+model NumberComparisonFilter {
+  /** The comparison operator to apply to the filter value */
+  operator: ComparisonOperators;
+
+  /** The value to use for the filter operation */
+  @example(1000)
+  value: numeric;
+}
+
+// ############################################################################
+// Number range filter
+// ############################################################################
+
+/** Filters by comparing a field to a numeric range */
+model NumberRangeFilter {
+  /** The operator to apply to the filter value */
+  operator: RangeOperators;
+
+  /** The value to use for the filter operation */
+  @example(#{ min: 1000, max: 10000 })
+  value: {
+    min: numeric;
+    max: numeric;
+  };
+}
+
+// ############################################################################
+// Number array filter
+// ############################################################################
+
+/** Filters by comparing a field to an array of numeric values */
+model NumberArrayFilter {
+  /** The operator to apply to the filter value */
+  operator: ArrayOperators;
+
+  /** The value to use for the filter operation */
+  @example(#[1000, 2000, 3000])
+  value: Array<numeric>;
+}