@common-grants/core 0.2.3 → 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.3",
+  "version": "0.3.0-alpha.1",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",
@@ -30,6 +30,18 @@
     "url": "https://github.com/HHS/simpler-grants-protocol/issues"
   },
   "homepage": "https://github.com/HHS/simpler-grants-protocol/tree/main/lib/core/#readme",
+  "scripts": {
+    "clean": "rimraf dist tsp-output",
+    "build": "tsc -p .",
+    "watch": "tsc -p . --watch",
+    "typespec": "tsp compile lib/main.tsp",
+    "prepare": "npm run build",
+    "lint": "eslint . --fix",
+    "format": "prettier --write . && tsp format lib",
+    "check:lint": "eslint",
+    "check:format": "prettier --check . && tsp format lib --check",
+    "checks": "npm run check:lint && npm run check:format"
+  },
   "keywords": [
     "typespec",
     "api",
@@ -39,34 +51,20 @@
   "author": "CommonGrants",
   "license": "CC0-1.0",
   "peerDependencies": {
-    "@typespec/compiler": "^1.5.0",
-    "@typespec/http": "^1.5.0",
-    "@typespec/json-schema": "^1.5.0",
-    "@typespec/openapi3": "^1.5.0",
-    "@typespec/openapi": "^1.5.0",
-    "@typespec/rest": "^0.75.0",
-    "@typespec/versioning": "^0.75.0"
+    "@typespec/compiler": "^1.1.0",
+    "@typespec/http": "^1.1.0",
+    "@typespec/json-schema": "1.0.0",
+    "@typespec/openapi3": "1.0.0",
+    "@typespec/rest": "0.70.0",
+    "@typespec/versioning": "^0.70.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.18.0",
     "@types/node": "^20.10.6",
     "eslint": "^9.18.0",
-    "globals": "^15.14.0",
     "prettier": "^3.4.2",
     "rimraf": "^5.0.5",
     "source-map-support": "^0.5.21",
     "typescript": "^5.3.3",
     "typescript-eslint": "^8.20.0"
-  },
-  "scripts": {
-    "clean": "rimraf dist tsp-output",
-    "build": "tsc -p .",
-    "watch": "tsc -p . --watch",
-    "typespec": "tsp compile lib/main.tsp",
-    "lint": "eslint . --fix",
-    "format": "prettier --write . && tsp format lib",
-    "check:lint": "eslint",
-    "check:format": "prettier --check . && tsp format lib --check",
-    "checks": "npm run check:lint && npm run check:format"
   }
-}
+}

package/LICENSE.md

@@ -1,34 +0,0 @@
-# License
-
-As a work of the [United States government](https://www.usa.gov/), this project
-is in the public domain within the United States of America.
-
-Additionally, we waive copyright and related rights in the work worldwide
-through the CC0 1.0 Universal public domain dedication.
-
-## CC0 1.0 Universal Summary
-
-This is a human-readable summary of the [Legal Code (read the full
-text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
-
-### No Copyright
-
-The person who associated a work with this deed has dedicated the work to the
-public domain by waiving all of their rights to the work worldwide under
-copyright law, including all related and neighboring rights, to the extent
-allowed by law.
-
-You can copy, modify, distribute, and perform the work, even for commercial
-purposes, all without asking permission.
-
-### Other Information
-
-In no way are the patent or trademark rights of any person affected by CC0, nor
-are the rights that other persons may have in the work or in how the work is
-used, such as publicity or privacy rights.
-
-Unless expressly stated otherwise, the person who associated a work with this
-deed makes no warranties about the work, and disclaims liability for all uses
-of the work, to the fullest extent permitted by applicable law. When using or
-citing the work, you should not imply endorsement by the author or the
-affirmer.