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

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

@@ -4,36 +4,63 @@ import "./timeline.tsp";
 import "../../fields/index.tsp";
 import "../../types.tsp";
 
-/** Namespace for Core that are specific to funding opportunities */
-namespace Core.Models.Opportunity;
+namespace CommonGrants.Models;
 
-using Core.Fields;
-using Core.Types;
+using CommonGrants.Fields;
+using CommonGrants.Types;
 
 // ########################################
 // Model definition
 // ########################################
 
-@doc("A funding opportunity") // Overrides internal docstrings when emitting OpenAPI
+/** 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 {
+ *   fieldType: CustomFieldType.string;
+ *
+ *   @example("Department of Transportation")
+ *   value: string;
+ * }
+ *
+ * model NewFields extends CustomFieldMap {
+ *   agency: Agency;
+ * }
+ *
+ * model CustomOpportunity extends OpportunityBase {
+ *   customFields: NewFields;
+ * }
+ * ```
+ */
+@doc("A funding opportunity")
 model OpportunityBase {
   /** Globally unique id for the opportunity */
   @visibility(Lifecycle.Read)
   id: uuid;
 
   /** Title or name of the funding opportunity */
+  @example("Small business grant program")
   title: string;
 
   /** Status of the opportunity */
   status: OppStatus;
 
   /** Description of the opportunity's purpose and scope */
+  @example("This program provides funding to small businesses to help them grow and create jobs")
   description: string;
 
   /** Details about the funding available */
-  fundingDetails: FundingDetails;
+  funding?: OppFunding;
 
   /** Key dates for the opportunity, such as when the application opens and closes */
-  keyDates: OppTimeline;
+  keyDates?: OppTimeline;
 
   /** URL for the original source of the opportunity */
   source?: url;
@@ -44,34 +71,3 @@ model OpportunityBase {
   // Spreads the fields from the Metadata model into the Opportunity model
   ...SystemMetadata;
 }
-
-// ########################################
-// Model examples
-// ########################################
-
-namespace OpportunityExamples {
-  /** A complete opportunity example with all optional fields defined */
-  const complete = #{
-    id: "049b4b15-f219-4037-901e-cd95ac32fbc8",
-    source: "https://grants.gov/opportunity/123",
-    title: "Healthcare Innovation Research Grant",
-    description: "Funding for innovative healthcare delivery solutions",
-    fundingDetails: FundingExamples.allFields,
-    keyDates: #[EventExamples.openDate, EventExamples.deadline],
-    customFields: #{
-      programArea: CustomFieldExamples.programArea,
-      eligibilityType: CustomFieldExamples.programArea,
-    },
-    ...MetadataExample.system,
-  };
-
-  /** A minimal opportunity example with only required fields */
-  const minimal = #{
-    id: "550e8400-e29b-41d4-a716-446655440001",
-    source: "https://grants.gov/opportunity/456",
-    title: "Small Business Innovation Grant",
-    description: "Supporting small business innovation projects",
-    fundingDetails: FundingExamples.onlyLimit,
-    ...MetadataExample.system,
-  };
-}

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

@@ -1,25 +1,28 @@
 import "../index.tsp";
 import "../../fields/index.tsp";
 
-namespace Core.Models.Opportunity;
+namespace CommonGrants.Models;
 
-using Core.Fields;
+using CommonGrants.Fields;
 
 // ########################################
 // Model definition
 // ########################################
 
 /** Details about the funding available for this opportunity */
-@example(FundingExamples.allFields, #{ title: "All fields defined" })
 @example(
-  FundingExamples.awardRange,
+  Examples.Funding.awardRange,
   #{ title: "Award range but no total limit" }
 )
 @example(
-  FundingExamples.onlyLimit,
+  Examples.Funding.onlyLimit,
   #{ title: "Total funding limit but no award range" }
 )
-model FundingDetails {
+@example(Examples.Funding.allFields, #{ title: "All fields defined" })
+model OppFunding {
+  /** Details about the funding available for this opportunity that don't fit other fields */
+  details?: string;
+
   /** Total amount of funding available for this opportunity */
   totalAmountAvailable?: Money;
 
@@ -43,8 +46,9 @@ model FundingDetails {
 // Model examples
 // ########################################
 
-namespace FundingExamples {
-  /** A FundingDetails example in which all of the fields are defined */
+/** Examples of the OppFunding model */
+namespace Examples.Funding {
+  /** An OppFunding example in which all of the fields are defined */
   const allFields = #{
     totalAmountAvailable: #{ amount: "1000000.00", currency: "USD" },
     minAwardAmount: #{ amount: "10000.00", currency: "USD" },
@@ -54,16 +58,18 @@ namespace FundingExamples {
     estimatedAwardCount: 10,
   };
 
-  /** A FundingDetails example that has an award range but no total limit */
+  /** An OppFunding example that has an award range but no total limit */
   const awardRange = #{
+    details: "We'll be awarding between $10,000 and $50,000 per recipient",
     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 */
+  /** An OppFunding example that has a total limit but no award range */
   const onlyLimit = #{
+    details: "This opportunity has a total funding limit of $1,000,000 but no specific award range",
     totalAmountAvailable: #{ amount: "1000000.00", currency: "USD" },
     estimatedAwardCount: 10,
   };

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

@@ -2,5 +2,6 @@ import "./status.tsp";
 import "./funding.tsp";
 import "./timeline.tsp";
 import "./base.tsp";
+import "./search.tsp";
 
-namespace Core.Models.Opportunity;
+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

@@ -1,7 +1,7 @@
 import "@typespec/json-schema";
 import "@typespec/openapi3";
 
-namespace Core.Models.Opportunity;
+namespace CommonGrants.Models;
 
 // ########################################
 // Opportunity status options
@@ -20,8 +20,10 @@ enum OppStatusOptions {
 // ########################################
 
 /** The status of the opportunity */
+@example(Examples.OppStatus.custom)
+@example(Examples.OppStatus.default)
 model OppStatus {
-  /** The status value */
+  /** The status value, from a predefined set of options */
   value: OppStatusOptions;
 
   /** A custom status value */
@@ -30,3 +32,21 @@ model OppStatus {
   /** 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

@@ -1,25 +1,25 @@
 import "../../fields/index.tsp";
 import "../../types.tsp";
 
-namespace Core.Models.Opportunity;
+namespace CommonGrants.Models;
 
-using Core.Fields;
-using Core.Types;
+using CommonGrants.Fields;
+using CommonGrants.Types;
 
 // ########################################
 // Model definition
 // ########################################
 
-/** Key dates in the opportunity's timeline, such as when the application opens and closes */
-@example(TimelineExamples.opportunity)
+/** 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.
    */
@@ -30,16 +30,26 @@ model OppTimeline {
 // Model examples
 // ########################################
 
-namespace TimelineExamples {
+/** Examples of the OppTimeline model */
+namespace Examples.Timeline {
   const opportunity = #{
-    appOpens: EventExamples.openDate,
-    appDeadline: EventExamples.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/error.tsp

@@ -1,6 +1,6 @@
 import "@typespec/http";
 
-namespace Core.Responses;
+namespace CommonGrants.Responses;
 
 /** A standard error response schema, used to create custom error responses
  *

package/lib/core/responses/index.tsp

@@ -3,4 +3,25 @@ import "@typespec/http";
 import "./error.tsp";
 import "./success.tsp";
 
-namespace Core.Responses;
+using TypeSpec.JsonSchema;
+
+/** 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;
+ * }
+ * ```
+ */
+@jsonSchema
+namespace CommonGrants.Responses;