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

package/README.md

@@ -35,30 +35,31 @@ The Opportunity model is templated to support custom fields. First define your c
 
 import "@common-grants/core"; // Import the base specification library
 
-// Allows us to use models defined in the specification library
-// without prefixing each model with `CommonGrants.Models.`
+// 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;
+  name: "Agency";
+  fieldType: CustomFieldType.string;
 
-    @example("Department of Transportation")
-    value: string;
+  @example("Department of Transportation")
+  value: string;
 
-    description: "The agency responsible for this opportunity";
+  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;
-    }
-};
+  customFields: {
+    agency: Agency;
+  };
+}
 ```
 
 ### Override default routes
@@ -75,13 +76,14 @@ using CommonGrants.Routes;
 using TypeSpec.Http;
 
 @tag("Search")
-@route("/opportunities")
+@route("/common-grants/opportunities")
 namespace CustomAPI.CustomRoutes {
-    alias OpportunitiesRouter = Opportunities;
+  alias OpportunitiesRouter = Opportunities;
 
-    // Use the default model for list but custom model for read
-    op list is OpportunitiesRouter.list;
-    op read is OpportunitiesRouter.read<CustomModels.CustomOpportunity>;
+  // 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>;
 }
 ```
 
@@ -98,9 +100,8 @@ import "./routes.tsp"; // Import the routes from above
 
 using TypeSpec.Http;
 
-@service({
-    title: "Custom API",
-})
+/** Description of your API goes here */
+@service(#{ title: "Custom API" })
 namespace CustomAPI;
 ```
 
@@ -126,46 +127,4 @@ Both strategies will generate an OpenAPI specification in the `tsp-output/` dire
 
 - 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.
-
-## 💻 Contributing to the library
-
-### Project structure
-
-The `specs/` sub-directory is organized like this:
-
-```
-.
-├── lib/                # Defines reusable models and routes for the library
-│   ├── models/         # Defines base models like Opportunity, CustomField, etc.
-│   ├── routes/         # Defines base routes like GET /opportunities
-│   └── main.tsp        # Exposes models and routes from the root of the library
-|
-├── src/
-│   ├── index.ts        # Defines the entry point for the library
-│   └── lib.ts          # Creates a new TypeSpec library definition
-|
-├── dist/               # .gitignored directory that stores the output of `npm build`
-|
-├── package.json        # Manages dependencies, commands, and library metadata
-├── tsconfig.json       # Manages TypeScript configuration
-└── tspconfig.yaml      # Manages TypeSpec configuration
-```
-
-### Pre-requisites
-
-Node version 20 or later. Check with `node --version`
-
-### Commands
-
-All commands are run from the root of the project, from a terminal:
-
-| Command                | Action                                     |
-| :--------------------- | :----------------------------------------- |
-| `npm install`          | Installs dependencies                      |
-| `npm run build`        | Build package locally                      |
-| `npm pack`             | Create a tarball from the package          |
-| `npm typespec`         | Compile and emit the library with TypeSpec |
-| `npm run format`       | Run automatic formatting and fix issues    |
-| `npm run lint`         | Run automatic linting and fix issues       |
-| `npm run check:format` | Check formatting, fail if issues are found |
-| `npm run check:lint`   | Check linting, fail if issues are found    |
+- See the [CommonGrants CLI](https://www.npmjs.com/package/@common-grants/cli) for more developer tools related to the CommonGrants protocol.

package/lib/api.tsp

@@ -1,29 +1,44 @@
 // Import Schemas.and Routes to make them available outside the package
 import "./core/index.tsp";
 import "@typespec/http";
-
-using Core;
+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",
-})
+@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")
-@route("/opportunities")
+@route("/common-grants/opportunities")
 namespace Opportunities {
   alias Router = Routes.Opportunities;
 
   @tag("required")
-  op List is Router.list;
+  op list is Router.list;
 
   @tag("required")
-  op Read is Router.read;
+  op read is Router.read;
+
+  @tag("optional")
+  op search is Router.search;
 }

package/lib/core/fields/address.tsp

@@ -0,0 +1,86 @@
+namespace CommonGrants.Fields;
+
+/** A mailing address. */
+@example(Examples.Address.apartment)
+model Address {
+  /** The primary street address line. */
+  street1: string;
+
+  /** Additional street address information (e.g., apartment number, suite, etc.). */
+  street2?: string;
+
+  /** The city or municipality name. */
+  city: string;
+
+  /** The state, province, or region name. */
+  stateOrProvince: string;
+
+  /** The country name or ISO country code. */
+  country: string;
+
+  /** The postal or ZIP code for the address. */
+  postalCode: string;
+
+  /** The latitude coordinate of the address location. */
+  latitude?: numeric;
+
+  /** The longitude coordinate of the address location. */
+  longitude?: numeric;
+
+  /** Additional geospatial data in GeoJSON format. */
+  geography?: Record<unknown>;
+}
+
+/** A collection of addresses. */
+@example(Examples.Address.personalCollection)
+@example(Examples.Address.orgCollection)
+model AddressCollection {
+  /** The primary address for a person or organization. */
+  primary: Address;
+
+  /** Additional addresses keyed by a descriptive label (e.g., "work", "home", "international"). */
+  otherAddresses?: Record<Address>;
+}
+
+namespace Examples.Address {
+  const apartment = #{
+    street1: "123 Main St",
+    city: "Anytown",
+    stateOrProvince: "CA",
+    country: "US",
+    postalCode: "12345",
+  };
+
+  const orgAddress = #{
+    street1: "456 Main St",
+    street2: "Suite 100",
+    city: "Anytown",
+    stateOrProvince: "CA",
+    country: "US",
+    postalCode: "12345",
+  };
+
+  const international = #{
+    street1: "123 Rue Principale",
+    city: "Montreal",
+    stateOrProvince: "QC",
+    country: "CA",
+    postalCode: "H2Y 1C6",
+  };
+
+  const personalCollection = #{
+    primary: Examples.Address.apartment,
+    otherAddresses: #{
+      work: Examples.Address.apartment,
+      home: Examples.Address.apartment,
+    },
+  };
+
+  const orgCollection = #{
+    primary: Examples.Address.orgAddress,
+    otherAddresses: #{
+      satellite: Examples.Address.orgAddress,
+      international: Examples.Address.international,
+    },
+  };
+}

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

@@ -1,4 +1,4 @@
-namespace Core.Fields;
+namespace CommonGrants.Fields;
 
 // ########################################
 // Field types definition
@@ -8,6 +8,7 @@ namespace Core.Fields;
 enum CustomFieldType {
   string,
   number,
+  integer,
   boolean,
   object,
   array,
@@ -25,7 +26,7 @@ enum CustomFieldType {
  * model Agency extends CustomField {
  *   name: "agency";
  *
- *   type: CustomFieldType.string;
+ *   fieldType: CustomFieldType.string;
  *
  *   @example("Department of Transportation")
  *   value: string;
@@ -35,20 +36,20 @@ enum CustomFieldType {
  * ```
  */
 @example(
-  CustomFieldExamples.programArea,
+  Examples.CustomField.programArea,
   #{ title: "String field for program area" }
 )
 @example(
-  CustomFieldExamples.eligibilityTypes,
+  Examples.CustomField.eligibilityTypes,
   #{ title: "Array field for eligibility types" }
 )
-@doc("A custom field on a model") // Overrides internal docstrings when emitting OpenAPI
+@doc("A custom field on a model")
 model CustomField {
   /** Name of the custom field */
   name: string;
 
   /** The JSON schema type to use when de-serializing the `value` field */
-  type: CustomFieldType;
+  fieldType: CustomFieldType;
 
   /** Link to the full JSON schema for this custom field */
   schema?: url;
@@ -64,11 +65,12 @@ model CustomField {
 // Model examples
 // ########################################
 
-namespace CustomFieldExamples {
+/** Examples of the CustomField model */
+namespace Examples.CustomField {
   /** An example of a string custom field */
   const programArea = #{
     name: "programArea",
-    type: CustomFieldType.string,
+    fieldType: CustomFieldType.string,
     value: "Healthcare Innovation",
     description: "Primary focus area of the grant program",
     schema: "https://example.com/program-areas.json",
@@ -77,7 +79,7 @@ namespace CustomFieldExamples {
   /** An example of an array custom field */
   const eligibilityTypes = #{
     name: "eligibilityType",
-    type: CustomFieldType.array,
+    fieldType: CustomFieldType.array,
     value: #["nonprofit", "academic"],
     description: "Types of eligible organizations",
   };

package/lib/core/fields/email.tsp

@@ -0,0 +1,35 @@
+import "../types.tsp";
+
+namespace CommonGrants.Fields;
+
+/** An email address. */
+alias Email = Types.email; // Exposes Email from CommonGrants.Fields
+
+/** A collection of email addresses. */
+@example(Examples.Email.personalCollection)
+model EmailCollection {
+  /** The primary email address for a person or organization. */
+  primary: Types.email;
+
+  /** Additional email addresses keyed by a descriptive label (e.g., "work", "personal", "support"). */
+  otherEmails?: Record<Types.email>;
+}
+
+namespace Examples.Email {
+  const personalCollection = #{
+    primary: "john.doe@example.com",
+    otherEmails: #{
+      work: "john.doe@work.com",
+      personal: "john.doe@gmail.com",
+      school: "john.doe@school.edu",
+    },
+  };
+
+  const orgCollection = #{
+    primary: "info@example.com",
+    otherEmails: #{
+      support: "support@example.com",
+      marketing: "marketing@example.com",
+    },
+  };
+}

package/lib/core/fields/event.tsp

@@ -1,27 +1,120 @@
 import "../types.tsp";
 
-namespace Core.Fields;
+namespace CommonGrants.Fields;
 
-using Core.Types;
+using CommonGrants.Types;
 
 // ########################################
-// Model definition
+// Event type
 // ########################################
 
-/** Description of an event that has a date (and possible time) associated with it */
-@example(EventExamples.deadline, #{ title: "Application deadline with time" })
-@example(EventExamples.openDate, #{ title: "Opening date without time" })
-model Event {
+/** Type of event (e.g., a single date, a date range, or a custom event)
+ *
+ * - singleDate: A single date (and possible time)
+ * - dateRange: A period of time with a start and end date
+ * - other: Other event type (e.g., a recurring event)
+ */
+enum EventType {
+  /** A single date with no time */
+  singleDate,
+
+  /** A range of dates with no time */
+  dateRange,
+
+  /** Other event type */
+  other,
+}
+
+// ########################################
+// Event
+// ########################################
+
+/** Union of all event types */
+union Event {
+  /** A single date event */
+  singleDate: SingleDateEvent,
+
+  /** A date range event */
+  dateRange: DateRangeEvent,
+
+  /** Other event type */
+  other: OtherEvent,
+}
+
+// ########################################
+// Event base
+// ########################################
+
+/** Base model for all events */
+@discriminator("eventType")
+model EventBase {
   /** Human-readable name of the event (e.g., 'Application posted', 'Question deadline') */
   name: string;
 
+  /** Type of event */
+  eventType: EventType;
+
+  /** Description of what this event represents */
+  description?: string;
+}
+
+// ########################################
+// Single date event
+// ########################################
+
+/** Description of an event that has a date (and possible time) associated with it */
+@example(Examples.Event.postedDate, #{ title: "Opportunity posted date" })
+@example(Examples.Event.closeDate, #{ title: "Opportunity close date" })
+model SingleDateEvent extends EventBase {
+  /** Type of event */
+  eventType: EventType.singleDate;
+
   /** 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 */
+// ########################################
+// Date range event
+// ########################################
+
+/** Description of an event that has a start and end date (and possible time) associated with it */
+@example(Examples.Event.performancePeriod, #{ title: "Period of performance" })
+@example(Examples.Event.applicationPeriod, #{ title: "Application period" })
+model DateRangeEvent extends EventBase {
+  /** Type of event */
+  eventType: EventType.dateRange;
+
+  /** Start date of the event in ISO 8601 format: YYYY-MM-DD */
+  startDate: isoDate;
+
+  /** Start time of the event in ISO 8601 format: HH:MM:SS */
+  startTime?: isoTime;
+
+  /** End date of the event in ISO 8601 format: YYYY-MM-DD */
+  endDate: isoDate;
+
+  /** End time of the event in ISO 8601 format: HH:MM:SS */
+  endTime?: isoTime;
+}
+
+// ########################################
+// Custom event
+// ########################################
+
+/** Description of an event that is not a single date or date range */
+@example(Examples.Event.infoSessions, #{ title: "Info sessions" })
+model OtherEvent extends EventBase {
+  /** Type of event */
+  eventType: EventType.other;
+
+  /** Details of the event's timeline (e.g. "Every other Tuesday") */
+  details?: string;
+
+  /** Description of the event */
+  @example("Applications begin being accepted")
   description?: string;
 }
 
@@ -29,19 +122,48 @@ model Event {
 // Model examples
 // ########################################
 
-namespace EventExamples {
+namespace Examples.Event {
   /** An example of a deadline event with a specific time */
-  const deadline = #{
-    name: "Application Deadline",
+  const closeDate = #{
+    name: "Opportunity close date",
+    eventType: EventType.singleDate,
     date: isoDate.fromISO("2024-12-31"),
     time: isoTime.fromISO("17:00:00"),
-    description: "Final submission deadline for all grant applications",
+    description: "Opportunity closes for all applications",
   };
 
-  /** An example of an opening date without a specific time */
-  const openDate = #{
-    name: "Open Date",
+  /** An example of an opportunity posted date without a specific time */
+  const postedDate = #{
+    name: "Application posted date",
+    eventType: EventType.singleDate,
     date: isoDate.fromISO("2024-01-15"),
-    description: "Applications begin being accepted",
+    description: "Opportunity is posted publicly",
+  };
+
+  /** Period of application for the grant */
+  const applicationPeriod = #{
+    name: "Application period",
+    eventType: EventType.dateRange,
+    startDate: isoDate.fromISO("2024-01-01"),
+    endDate: isoDate.fromISO("2024-01-31"),
+    endTime: isoTime.fromISO("17:00:00"),
+    description: "Primary application period for the grant opportunity",
+  };
+
+  /** Period of performance for the grant */
+  const performancePeriod = #{
+    name: "Period of Performance",
+    eventType: EventType.dateRange,
+    startDate: isoDate.fromISO("2024-01-01"),
+    endDate: isoDate.fromISO("2024-12-31"),
+    description: "Period of performance for the grant",
+  };
+
+  /** Info sessions for the opportunity */
+  const infoSessions = #{
+    name: "Info sessions",
+    eventType: EventType.other,
+    details: "Every other Tuesday at 10:00 AM during the application period",
+    description: "Info sessions for the opportunity",
   };
 }

package/lib/core/fields/index.tsp

@@ -2,5 +2,27 @@ import "./custom-field.tsp";
 import "./metadata.tsp";
 import "./money.tsp";
 import "./event.tsp";
+import "./address.tsp";
+import "./name.tsp";
+import "./phone.tsp";
+import "./pcs.tsp";
+import "./email.tsp";
 
-namespace Internals.Schemas.Fields;
+using TypeSpec.JsonSchema;
+
+/** 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;
+ * }
+ * ```
+ */
+@jsonSchema
+namespace CommonGrants.Fields;

package/lib/core/fields/metadata.tsp

@@ -1,4 +1,4 @@
-namespace Core.Fields;
+namespace CommonGrants.Fields;
 
 // ########################################
 // Model definition
@@ -18,7 +18,7 @@ namespace Core.Fields;
  * }
  * ```
  * */
-@example(MetadataExample.system)
+@example(Examples.Metadata.system)
 model SystemMetadata {
   /** The timestamp (in UTC) at which the record was created. */
   @visibility(Lifecycle.Read)
@@ -33,7 +33,8 @@ model SystemMetadata {
 // Model examples
 // ########################################
 
-namespace MetadataExample {
+/** 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

@@ -1,21 +1,21 @@
 import "../types.tsp";
 
-namespace Core.Fields;
+namespace CommonGrants.Fields;
 
-using Core.Types;
+using CommonGrants.Types;
 
 // ########################################
 // Model definition
 // ########################################
 
-/** A monetary amount and the currency in which its denominated */
-@example(MoneyExamples.usdWithCents, #{ title: "US dollars and cents" })
+/** A monetary amount and the currency in which it's denominated */
+@example(Examples.Money.usdWithCents, #{ title: "US dollars and cents" })
 @example(
-  MoneyExamples.euroWithoutCents,
+  Examples.Money.euroWithoutCents,
   #{ title: "Euros displayed without cents" }
 )
 @example(
-  MoneyExamples.usdNegative,
+  Examples.Money.usdNegative,
   #{ title: "A negative amount of US dollars and cents" }
 )
 model Money {
@@ -30,7 +30,8 @@ model Money {
 // Model examples
 // ########################################
 
-namespace MoneyExamples {
+/** Examples of the Money model */
+namespace Examples.Money {
   /** An example of a positive USD amount with cents */
   const usdWithCents = #{ amount: "10000.50", currency: "USD" };
 

package/lib/core/fields/name.tsp

@@ -0,0 +1,30 @@
+namespace CommonGrants.Fields;
+
+/** A person's name. */
+@example(Examples.Name.janeDoe)
+model Name {
+  /** Honorific prefix (e.g., Mr., Mrs., Dr., Prof.). */
+  prefix?: string;
+
+  /** The person's first or given name. */
+  firstName: string;
+
+  /** The person's middle name or names. */
+  middleName?: string;
+
+  /** The person's last name or family name. */
+  lastName: string;
+
+  /** Name suffix (e.g., Jr., Sr., III, Ph.D.). */
+  suffix?: string;
+}
+
+namespace Examples.Name {
+  const janeDoe = #{
+    prefix: "Dr.",
+    firstName: "Jane",
+    middleName: "Edward",
+    lastName: "Doe",
+    suffix: "Jr.",
+  };
+}