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

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

@@ -10,16 +10,16 @@ using CommonGrants.Types;
 // Model definition
 // ########################################
 
-/** Key dates in the opportunity's timeline, such as when the application opens and closes */
+/** Key dates and events in the opportunity's timeline, such as when the opportunity is posted and closes */
 @example(Examples.Timeline.opportunity)
 model OppTimeline {
-  /** The date (and time) at which the opportunity begins accepting applications */
-  appOpens?: Event;
+  /** The date (and time) at which the opportunity is posted */
+  postDate?: Event;
 
-  /** The final deadline for submitting applications */
-  appDeadline?: Event;
+  /** The date (and time) at which the opportunity closes */
+  closeDate?: Event;
 
-  /** An optional map of other key dates in the opportunity timeline
+  /** An optional map of other key dates or events in the opportunity timeline
    *
    * Examples might include a deadline for questions, anticipated award date, etc.
    */
@@ -33,14 +33,23 @@ model OppTimeline {
 /** Examples of the OppTimeline model */
 namespace Examples.Timeline {
   const opportunity = #{
-    appOpens: Fields.Examples.Event.openDate,
-    appDeadline: Fields.Examples.Event.deadline,
+    postDate: Fields.Examples.Event.postedDate,
+    closeDate: Fields.Examples.Event.closeDate,
     otherDates: #{
       anticipatedAward: #{
         name: "Anticipated award date",
+        eventType: EventType.singleDate,
         date: isoDate.fromISO("2025-03-15"),
         description: "When we expect to announce awards for this opportunity.",
       },
+      applicationPeriod: Fields.Examples.Event.applicationPeriod,
+      performancePeriod: Fields.Examples.Event.performancePeriod,
+      infoSessions: #{
+        name: "Info sessions",
+        eventType: EventType.other,
+        details: "Every other Tuesday",
+        description: "Info sessions for the opportunity",
+      },
     },
   };
 }

package/lib/core/models/organization.tsp

@@ -0,0 +1,105 @@
+import "../fields/index.tsp";
+
+namespace CommonGrants.Models;
+
+/** An organization that can apply for grants. */
+@example(Examples.Organization.exampleOrg)
+model OrganizationBase {
+  /** The organization's unique identifier. */
+  id: Types.uuid;
+
+  /** The organization's legal name as registered with relevant authorities. */
+  name: string;
+
+  /** The organization's type within the Philanthropy Classification System (PCS). */
+  orgType?: Fields.PCSOrgType;
+
+  /** The organization's Employer Identification Number (EIN), a unique identifier assigned by the IRS. */
+  ein?: Types.employerTaxId;
+
+  /** The organization's Unique Entity Identifier (UEI) from SAM.gov, used for federal contracting. */
+  uei?: Types.samUEI;
+
+  /** The organization's Data Universal Numbering System (DUNS) number, a unique identifier for businesses. */
+  duns?: Types.duns;
+
+  /** Collection of physical addresses associated with the organization. */
+  addresses?: Fields.AddressCollection;
+
+  /** Collection of phone numbers associated with the organization. */
+  phones?: Fields.PhoneCollection;
+
+  /** Collection of email addresses associated with the organization. */
+  emails?: Fields.EmailCollection;
+
+  /** The organization's mission statement. */
+  mission?: string;
+
+  /** The calendar year the organization was founded. */
+  yearFounded?: Types.calendarYear;
+
+  /** Collection of the organization's social media and web presence links. */
+  socials?: OrgSocialLinks;
+
+  /** Custom fields for the organization. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// OrgSocialLinks
+// #########################################################
+
+/** A collection of social media and web presence links for an organization. */
+@example(Examples.Organization.exampleSocials)
+model OrgSocialLinks {
+  /** The organization's primary website URL. */
+  website?: url;
+
+  /** The organization's Facebook profile URL. */
+  facebook?: url;
+
+  /** The organization's Twitter/X profile URL. */
+  twitterOrX?: url;
+
+  /** The organization's BlueSky profile URL. */
+  bluesky?: url;
+
+  /** The organization's Instagram profile URL. */
+  instagram?: url;
+
+  /** The organization's LinkedIn profile URL. */
+  linkedin?: url;
+
+  /** Additional social media profiles not covered by the standard fields. */
+  otherSocials?: Record<url>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Organization {
+  const exampleOrg = #{
+    id: "083b4567-e89d-42c8-a439-6c1234567890",
+    name: "Example Organization",
+    orgType: Fields.Examples.PCS.orgTypeTerm,
+    ein: "12-3456789",
+    uei: "ABC1234567890",
+    duns: "123456789012",
+    addresses: Fields.Examples.Address.orgCollection,
+    phones: Fields.Examples.Phone.orgCollection,
+    emails: Fields.Examples.Email.orgCollection,
+    mission: "To provide support and resources to the community.",
+    yearFounded: "2024",
+    socials: exampleSocials,
+  };
+
+  const exampleSocials = #{
+    website: "https://www.example.com",
+    facebook: "https://www.facebook.com/example",
+    twitterOrX: "https://x.com/example",
+    instagram: "https://www.instagram.com/example",
+    linkedin: "https://www.linkedin.com/company/example",
+    otherSocials: #{ youtube: "https://www.youtube.com/example" },
+  };
+}

package/lib/core/models/person.tsp

@@ -0,0 +1,43 @@
+import "../fields/index.tsp";
+import "../types.tsp";
+
+namespace CommonGrants.Models;
+
+/** A person affiliated with an organization or grant application. */
+@example(Examples.Person.examplePerson)
+model PersonBase {
+  /** The person's full name, including all relevant components (first, middle, last, etc.). */
+  name: Fields.Name;
+
+  /** The person's title, if applicable. */
+  title?: string;
+
+  /** Collection of physical addresses associated with the person. */
+  addresses?: Fields.AddressCollection;
+
+  /** Collection of phone numbers associated with the person. */
+  phones?: Fields.PhoneCollection;
+
+  /** Collection of email addresses associated with the person. */
+  emails?: Fields.EmailCollection;
+
+  /** The person's date of birth. */
+  dateOfBirth?: Types.isoDate;
+
+  /** Custom fields for the person. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Person {
+  const examplePerson = #{
+    name: Fields.Examples.Name.janeDoe,
+    title: "Chief Executive Officer",
+    addresses: Fields.Examples.Address.personalCollection,
+    phones: Fields.Examples.Phone.personalCollection,
+    emails: Fields.Examples.Email.personalCollection,
+  };
+}

package/lib/core/pagination.tsp

@@ -0,0 +1,56 @@
+import "@typespec/http";
+
+using TypeSpec.Http;
+using TypeSpec.JsonSchema;
+/** Models and utilities for pagination */
+@jsonSchema
+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 PaginatedResultsInfo {
+  /** 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/index.tsp

@@ -3,6 +3,8 @@ import "@typespec/http";
 import "./error.tsp";
 import "./success.tsp";
 
+using TypeSpec.JsonSchema;
+
 /** A standardized set of response schemas for CommonGrants API routes
  *
  * @example How to use the `Responses` namespace
@@ -21,4 +23,5 @@ import "./success.tsp";
  * }
  * ```
  */
+@jsonSchema
 namespace CommonGrants.Responses;

package/lib/core/responses/success.tsp

@@ -1,7 +1,13 @@
+import "../pagination.tsp";
+import "../sorting.tsp";
 import "@typespec/http";
 
 namespace CommonGrants.Responses;
 
+// ############################################################################
+// Default success response
+// ############################################################################
+
 model Success {
   @example(200)
   status: int32;
@@ -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/opportunities.tsp

@@ -1,6 +1,6 @@
 import "../models/index.tsp";
 import "../responses/index.tsp";
-import "./utils.tsp";
+import "../pagination.tsp";
 
 // Define the top-level namespace for CommonGrants routes
 namespace CommonGrants.Routes;
@@ -19,7 +19,7 @@ using TypeSpec.Http;
  * 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;
@@ -35,6 +35,10 @@ using TypeSpec.Http;
  * ```
  */
 interface Opportunities {
+  // ###############################
+  // List opportunities
+  // ###############################
+
   /** `GET /opportunities/` Get a paginated list of opportunities
    *
    * @template T Type of the paginated response model.
@@ -44,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
    *
@@ -58,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,3 +1,5 @@
+using TypeSpec.JsonSchema;
+
 /** A collection of base data types used throughout the CommonGrants API
  *
  * @example How to use the `Types` namespace
@@ -16,21 +18,43 @@
  * }
  * ```
  */
+@jsonSchema
 namespace CommonGrants.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 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]*$",
@@ -40,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;