@common-grants/core 0.2.2 → 0.3.0-alpha.1

package/lib/api.tsp

@@ -31,9 +31,17 @@ using Versioning;
   }
 )
 @tagMetadata("Forms", #{ description: "Endpoints related to forms" })
+@tagMetadata(
+  "Application Reviews",
+  #{
+    description: "Endpoints related to reviewing applications for a given competition",
+  }
+)
 @tagMetadata(
   "Applications",
-  #{ description: "Endpoints related to applications for a given competition" }
+  #{
+    description: "Endpoints related to submitting applications for a given competition",
+  }
 )
 @tagMetadata(
   "Competitions",
@@ -122,6 +130,14 @@ namespace Applications {
 
   @added(Versions.v0_2)
   op submitApplication is ApplicationRouter.submitApplication;
+
+  // ################################
+  // Search applications
+  // ################################
+
+  @added(Versions.v0_3)
+  @tag("Application Reviews")
+  op searchApplications is ApplicationRouter.searchApplications;
 }
 
 // #########################################################

package/lib/core/fields/file.tsp

@@ -47,4 +47,24 @@ namespace Examples.File {
     createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
     lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
   };
+
+  const excelFile = #{
+    downloadUrl: "https://example.com/excel.xlsx",
+    name: "excel.xlsx",
+    description: "The excel file for the application",
+    sizeInBytes: 1000,
+    mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
+  };
+
+  const zipFile = #{
+    downloadUrl: "https://example.com/application.zip",
+    name: "application.zip",
+    description: "The zip file for the application",
+    sizeInBytes: 50000,
+    mimeType: "application/zip",
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
+  };
 }

package/lib/core/models/application.tsp

@@ -13,6 +13,10 @@ model ApplicationBase {
   /** The unique identifier for the competition */
   competitionId: Types.uuid;
 
+  /** The unique identifier for the opportunity being applied to */
+  @Versioning.added(CommonGrants.Versions.v0_3)
+  opportunityId: Types.uuid;
+
   /** The form responses for the application */
   formResponses: Record<AppFormResponse>;
 
@@ -84,6 +88,79 @@ model AppFormResponse {
   ...FormResponseBase;
 }
 
+// #########################################################
+// AppFilters
+// #########################################################
+
+/** Filters to apply when searching for applications */
+@Versioning.added(CommonGrants.Versions.v0_3)
+model AppFilters {
+  /** The default filters to apply to the search */
+  ...AppDefaultFilters;
+
+  /** Additional implementation-defined filters to apply to the search */
+  customFilters?: Record<Filters.DefaultFilter>;
+}
+
+/** The standard set of filters supported for application searches */
+@Versioning.added(CommonGrants.Versions.v0_3)
+model AppDefaultFilters extends Record<Filters.DefaultFilter> {
+  /** `opportunityId` matches one of the following values */
+  @example(#{
+    operator: Filters.ArrayOperators.in,
+    value: #["ad3b469a-d89a-42d3-c439-6c1234567890"],
+  })
+  opportunityId?: Filters.StringArrayFilter;
+
+  /** `competitionId` matches one of the following values */
+  @example(#{
+    operator: Filters.ArrayOperators.in,
+    value: #["123e4567-e89b-12d3-a456-426614174000"],
+  })
+  competitionId?: Filters.StringArrayFilter;
+
+  /** `submittedAt` is between the given range */
+  @example(#{
+    operator: Filters.RangeOperators.between,
+    value: #{
+      min: Types.isoDate.fromISO("2025-01-01"),
+      max: Types.isoDate.fromISO("2025-01-30"),
+    },
+  })
+  submittedAtRange?: Filters.DateRangeFilter;
+
+  /** `status.value` matches one of the following values */
+  @example(#{
+    operator: Filters.ArrayOperators.in,
+    value: #["submitted", "accepted"],
+  })
+  status?: Filters.StringArrayFilter;
+}
+
+// #########################################################
+// AppSorting
+// #########################################################
+
+/** The fields that can be used to sort applications */
+@Versioning.added(CommonGrants.Versions.v0_3)
+enum AppSortBy {
+  lastModifiedAt,
+  createdAt,
+  submittedAt,
+  status: "status.value",
+  opportunityId,
+  competitionId,
+  custom,
+}
+
+/** Sorting parameters for applications */
+@Versioning.added(CommonGrants.Versions.v0_3)
+model AppSorting extends Sorting.SortBodyParams {
+  /** The field to sort by */
+  @example(AppSortBy.opportunityId)
+  sortBy: AppSortBy;
+}
+
 // #########################################################
 // Examples
 // #########################################################
@@ -110,14 +187,36 @@ namespace Examples.Application {
     ...Examples.FormResponse.formResponse,
   };
 
+  const attachmentsCustomField = #{
+    name: "attachments",
+    fieldType: Fields.CustomFieldType.object,
+    value: #{
+      contacts: Fields.Examples.File.pdfFile,
+      budget: Fields.Examples.File.excelFile,
+    },
+    description: "The attachments for the application",
+  };
+
+  const applicationZipFileCustomField = #{
+    name: "applicationZipFile",
+    fieldType: Fields.CustomFieldType.object,
+    value: Fields.Examples.File.zipFile,
+    description: "The zip file for the application",
+  };
+
   const applicationBase = #{
     id: "123e4567-e89b-12d3-a456-426614174000",
     name: "My Application",
     competitionId: "123e4567-e89b-12d3-a456-426614174000",
+    opportunityId: "ad3b469a-d89a-42d3-c439-6c1234567890",
     formResponses: #{ formA: formResponse },
     status: inProgressStatus,
     submittedAt: null,
     createdAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
     lastModifiedAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
+    customFields: #{
+      attachments: attachmentsCustomField,
+      applicationZipFile: applicationZipFileCustomField,
+    },
   };
 }

package/lib/core/models/competition.tsp

@@ -83,7 +83,7 @@ enum CompetitionStatusOptions {
 @example(Examples.Competition.forms)
 model CompetitionForms {
   /** The forms for the competition */
-  forms: Record<Models.Form>;
+  forms: Record<Models.FormBase>;
 
   /** The validation rules for the competition forms */
   validation?: Record<unknown>;

package/lib/core/models/form.tsp

@@ -9,7 +9,8 @@ namespace CommonGrants.Models;
 /** A form for collecting data from a user. */
 @example(Examples.Form.form)
 @Versioning.added(CommonGrants.Versions.v0_2)
-model Form {
+@Versioning.renamedFrom(CommonGrants.Versions.v0_3, "Form")
+model FormBase {
   /** The form's unique identifier. */
   id: Types.uuid;
 
@@ -19,6 +20,9 @@ model Form {
   /** The form's description. */
   description?: string;
 
+  @Versioning.added(CommonGrants.Versions.v0_3)
+  version?: string;
+
   /** The form's instructions. */
   instructions?: string | Fields.File[];
 
@@ -36,6 +40,9 @@ model Form {
 
   /** Custom attributes about the form itself, not custom fields within the form. */
   customFields?: Record<Fields.CustomField>;
+
+  /** The system metadata for the form. */
+  ...Fields.SystemMetadata;
 }
 
 // #########################################################
@@ -74,6 +81,8 @@ namespace Examples.Form {
     uiSchema: uiSchema,
     mappingToCommonGrants: mappingToCommonGrants,
     mappingFromCommonGrants: mappingFromCommonGrants,
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
   };
 
   const formSchema = #{

package/lib/core/routes/applications.tsp

@@ -63,4 +63,20 @@ interface Applications {
     | Responses.ApplicationSubmissionError
     | Responses.NotFound
     | Responses.Unauthorized;
+
+  // ###############################
+  // Search applications
+  // ###############################
+
+  @summary("Search applications")
+  @doc("Search for applications. Note: The search results for a given query will depend on the scopes attached to the API token used to make the request.")
+  @get
+  @route("/search")
+  searchApplications(
+    /** The filters to apply to the search */
+    @query filters: Models.AppFilters,
+
+    /** The sorting to apply to the search */
+    @query sorting: Models.AppSorting,
+  ): Responses.Filtered<Models.ApplicationBase, Models.AppFilters>;
 }

package/lib/core/routes/forms.tsp

@@ -22,7 +22,9 @@ interface Forms {
   @summary("List forms")
   @doc("Get a paginated list of forms, sorted by `lastModifiedAt` with most recent first.")
   @get
-  list(...Pagination.PaginatedQueryParams): Responses.Paginated<Models.Form>;
+  list(
+    ...Pagination.PaginatedQueryParams,
+  ): Responses.Paginated<Models.FormBase>;
 
   // ###############################
   // View form details
@@ -34,5 +36,5 @@ interface Forms {
   read(
     /** The ID of the form to view */
     @path formId: Types.uuid,
-  ): Responses.Ok<Models.Form>;
+  ): Responses.Ok<Models.FormBase>;
 }

package/lib/main.tsp

@@ -18,4 +18,5 @@ namespace CommonGrants;
 enum Versions {
   v0_1: "0.1.0",
   v0_2: "0.2.0",
+  v0_3: "0.3.0",
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common-grants/core",
-  "version": "0.2.2",
+  "version": "0.3.0-alpha.1",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",