@common-grants/core 0.1.1 → 0.2.0

package/lib/core/models/form-response.tsp

@@ -0,0 +1,99 @@
+namespace CommonGrants.Models;
+
+/** The base model for a form response */
+@example(Examples.FormResponse.formResponse)
+model FormResponseBase {
+  /** The unique identifier for the form response */
+  id: Types.uuid;
+
+  /** The form being responded to */
+  formId: Types.uuid;
+
+  /** The response to the form */
+  response: Record<unknown>;
+
+  /** The status of the form response */
+  status: FormResponseStatus;
+
+  /** The validation errors for the form response */
+  validationErrors?: Array<unknown>;
+
+  /** Custom attributes about the form response */
+  customFields?: Record<Fields.CustomField>;
+
+  /** The system metadata for the form response */
+  ...Fields.SystemMetadata;
+}
+
+// #########################################################
+// FormResponseStatus
+// #########################################################
+
+/** The status of the form response */
+@example(Examples.FormResponse.inProgressStatus)
+model FormResponseStatus {
+  /** The status of the form response, from a predefined set of options */
+  value: FormResponseStatusOptions;
+
+  /** A custom value for the status */
+  customValue?: string;
+
+  /** A human-readable description of the status */
+  description?: string;
+}
+
+// #########################################################
+// FormResponseStatusOptions
+// #########################################################
+
+/** The set of values accepted for form response status:
+ * - `notStarted`: The form response has not been started
+ * - `inProgress`: The form response is in progress
+ * - `complete`: The form response is complete, meaning all required fields have been filled out and there are no validation errors
+ * - `custom`: A custom status
+ */
+enum FormResponseStatusOptions {
+  notStarted,
+  inProgress,
+  complete,
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.FormResponse {
+  const inProgressStatus = #{
+    value: FormResponseStatusOptions.inProgress,
+    description: "The form response is in progress",
+  };
+
+  const completeStatus = #{
+    value: FormResponseStatusOptions.complete,
+    description: "The form response is complete",
+  };
+
+  const formResponse = #{
+    id: "123e4567-e89b-12d3-a456-426614174000",
+    formId: "123e4567-e89b-12d3-a456-426614174000",
+    response: #{
+      firstName: "John",
+      lastName: "Doe",
+      email: "john.doe@example.com",
+      phone: "123-456-7890",
+      address: #{
+        street: "123 Main St",
+        city: "Anytown",
+        state: "CA",
+        zip: "12345",
+        country: null,
+      },
+    },
+    status: inProgressStatus,
+    validationErrors: #[
+      #{ field: "address.country", message: "Country is required" }
+    ],
+    createdAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
+    lastModifiedAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
+  };
+}

package/lib/core/models/form.tsp

@@ -0,0 +1,119 @@
+import "../index.tsp";
+
+namespace CommonGrants.Models;
+
+// #########################################################
+// Form
+// #########################################################
+
+/** A form for collecting data from a user. */
+@example(Examples.Form.form)
+model Form {
+  /** The form's unique identifier. */
+  id: Types.uuid;
+
+  /** The form's name. */
+  name: string;
+
+  /** The form's description. */
+  description?: string;
+
+  /** The form's instructions. */
+  instructions?: string | Fields.File[];
+
+  /** The form's JSON schema used to render the form and validate responses. */
+  jsonSchema?: FormJsonSchema;
+
+  /** The form's UI schema used to render the form in the browser. */
+  uiSchema?: FormUISchema;
+
+  /** A mapping from form schema to CommonGrants schema. */
+  mappingToCommonGrants?: Models.MappingSchema;
+
+  /** A mapping from CommonGrants schema to form schema. */
+  mappingFromCommonGrants?: Models.MappingSchema;
+
+  /** Custom attributes about the form itself, not custom fields within the form. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// FormJsonSchema
+// #########################################################
+
+/** A JSON schema used to validate form responses. */
+@example(Examples.Form.formSchema)
+model FormJsonSchema {
+  ...Record<unknown>;
+}
+
+// #########################################################
+// FormUISchema
+// #########################################################
+
+/** A UI schema used to render the form in the browser. */
+@example(Examples.Form.uiSchema)
+model FormUISchema {
+  ...Record<unknown>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Form {
+  const form = #{
+    id: "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a",
+    name: "Form A",
+    description: "Form A description",
+    instructions: "Form A instructions",
+    jsonSchema: formSchema,
+    uiSchema: uiSchema,
+    mappingToCommonGrants: mappingToCommonGrants,
+    mappingFromCommonGrants: mappingFromCommonGrants,
+  };
+
+  const formSchema = #{
+    $id: "formA.json",
+    type: "object",
+    properties: #{
+      name: #{ first: #{ type: "string" }, last: #{ type: "string" } },
+      email: #{ type: "string" },
+      phone: #{ type: "string" },
+    },
+  };
+
+  const uiSchema = #{
+    type: "VerticalLayout",
+    elements: #[
+      #{
+        type: "Group",
+        label: "Name",
+        elements: #[
+          #{ type: "Control", scope: "#/properties/name/first" },
+          #{ type: "Control", scope: "#/properties/name/last" }
+        ],
+      },
+      #{ type: "Control", scope: "#/properties/email" },
+      #{ type: "Control", scope: "#/properties/phone" }
+    ],
+  };
+
+  const mappingToCommonGrants = #{
+    name: #{
+      firstName: #{ field: "name.first" },
+      lastName: #{ field: "name.last" },
+    },
+    emails: #{ primary: #{ field: "email" } },
+    phones: #{ primary: #{ field: "phone" } },
+  };
+
+  const mappingFromCommonGrants = #{
+    name: #{
+      first: #{ field: "name.firstName" },
+      last: #{ field: "name.lastName" },
+    },
+    email: #{ field: "emails.primary" },
+    phone: #{ field: "phones.primary" },
+  };
+}

package/lib/core/models/index.tsp

@@ -5,7 +5,13 @@ import "@typespec/json-schema";
 import "./opportunity/index.tsp";
 import "./organization.tsp";
 import "./person.tsp";
+import "./proposal.tsp";
 import "./application.tsp";
+import "./competition.tsp";
+import "./form.tsp";
+import "./form-response.tsp";
+import "./mapping.tsp";
+import "./applicant-type.tsp";
 
 using TypeSpec.JsonSchema;
 

package/lib/core/models/mapping.tsp

@@ -0,0 +1,152 @@
+namespace CommonGrants.Models;
+
+// #########################################################
+// Mapping
+// #########################################################
+
+/** A mapping format for translating data from one schema to another.
+ *
+ * Example:
+ *
+ * The following mapping:
+ *
+ * ```json
+ * {
+ *   "id": { "const": "123" },
+ *   "opportunity": {
+ *     "status": {
+ *       "switch": {
+ *         "field": "summary.opportunity_status",
+ *         "case": { "active": "open", "inactive": "closed" },
+ *         "default": "custom",
+ *       },
+ *     },
+ *     "amount": { "field": "summary.opportunity_amount" },
+ *   }
+ * }
+ * ```
+ *
+ * Will translate the following data:
+ *
+ * ```json
+ * {
+ *   "id": "123",
+ *   "summary": {
+ *     "opportunity_status": "active",
+ *     "opportunity_amount": 100,
+ *   },
+ * }
+ * ```
+ *
+ * To the following data:
+ *
+ * ```json
+ * {
+ *   "id": "123",
+ *   "opportunity": { "status": "open", "amount": 100 },
+ * }
+ * ```
+ */
+@example(Examples.Mapping.flatRenaming)
+@example(Examples.Mapping.nestedRenaming)
+@example(Examples.Mapping.simpleSwitch)
+@example(Examples.Mapping.nestedSwitch)
+@example(Examples.Mapping.withLiteralValues)
+model MappingSchema {
+  ...Record<MappingFunction | MappingSchema>;
+}
+
+// #########################################################
+// MappingFunctions
+// #########################################################
+
+/** The set of supported mapping functions. */
+@example(Examples.Mapping.constId)
+@example(Examples.Mapping.amountField)
+@example(Examples.Mapping.statusSwitch)
+union MappingFunction {
+  `const`: MappingConstantFunction,
+  field: MappingFieldFunction,
+  switch: MappingSwitchFunction,
+}
+
+// #########################################################
+// MappingConstantFunction
+// #########################################################
+
+/** Returns a constant value. */
+@example(Examples.Mapping.constId)
+model MappingConstantFunction {
+  `const`: unknown;
+}
+
+// #########################################################
+// MappingFieldFunction
+// #########################################################
+
+/** Returns the value of a field in the source data. */
+@example(Examples.Mapping.amountField)
+model MappingFieldFunction {
+  field: string;
+}
+
+// #########################################################
+// MappingSwitchFunction
+// #########################################################
+
+/** Returns a new value based on the value of a field in the source data using a switch statement. */
+@example(Examples.Mapping.statusSwitch)
+model MappingSwitchFunction {
+  switch: {
+    /** The field in the source data to switch on. */
+    field: string;
+
+    /** An object mapping source field values to desired output values. */
+    case: Record<unknown>;
+
+    /** The default value to output if no case matches the source field value. */
+    default?: unknown;
+  };
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Mapping {
+  const constId = #{ `const`: "123" };
+  const amountField = #{ field: "summary.opportunity_amount" };
+  const statusField = #{ field: "summary.opportunity_status" };
+  const statusSwitch = #{
+    switch: #{
+      field: "summary.opportunity_status",
+      case: #{ active: "open", inactive: "closed" },
+      default: "custom",
+    },
+  };
+
+  const flatRenaming = #{
+    id: constId,
+    opportunityStatus: statusField,
+    opportunityAmount: amountField,
+  };
+
+  const nestedRenaming = #{
+    id: constId,
+    opportunity: #{ status: statusField, amount: amountField },
+  };
+
+  const simpleSwitch = #{
+    opportunityAmount: amountField,
+    opportunityStatus: statusSwitch,
+  };
+
+  const nestedSwitch = #{
+    opportunity: #{ status: statusSwitch, amount: amountField },
+  };
+
+  const withLiteralValues = #{
+    id: constId,
+    opportunity: #{ status: statusSwitch, amount: amountField },
+  };
+}

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

@@ -62,6 +62,9 @@ model OpportunityBase {
   /** Key dates for the opportunity, such as when the application opens and closes */
   keyDates?: OppTimeline;
 
+  /** The type of applicant for the opportunity */
+  acceptedApplicantTypes?: ApplicantType[];
+
   /** URL for the original source of the opportunity */
   source?: url;
 
@@ -71,3 +74,13 @@ model OpportunityBase {
   // Spreads the fields from the Metadata model into the Opportunity model
   ...SystemMetadata;
 }
+
+// ########################################
+// Opportunity details
+// ########################################
+
+/** A funding opportunity with additional details, like available competitions. */
+model OpportunityDetails extends OpportunityBase {
+  /** The competitions associated with the opportunity */
+  competitions?: CompetitionBase[];
+}

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

@@ -4,7 +4,12 @@ namespace CommonGrants.Models;
 // Opportunity status options
 // ########################################
 
-/** The set of values accepted for opportunity status */
+/** The set of values accepted for opportunity status:
+ * - `forecasted`: The opportunity is forecasted and not yet open for applications
+ * - `open`: The opportunity is open for applications
+ * - `closed`: The opportunity is no longer accepting applications
+ * - `custom`: A custom status
+ */
 enum OppStatusOptions {
   forecasted,
   open,
@@ -20,10 +25,10 @@ enum OppStatusOptions {
 @example(Examples.OppStatus.custom)
 @example(Examples.OppStatus.default)
 model OppStatus {
-  /** The status value, from a predefined set of options */
+  /** The status of the opportunity, from a predefined set of options */
   value: OppStatusOptions;
 
-  /** A custom status value */
+  /** A custom value for the status */
   customValue?: string;
 
   /** A human-readable description of the status */

package/lib/core/models/proposal.tsp

@@ -0,0 +1,173 @@
+namespace CommonGrants.Models;
+
+// #########################################################
+// ProposalBase
+// #########################################################
+
+/** A proposal for funding. */
+@example(Examples.Proposal.exampleProposal)
+model ProposalBase {
+  /** The title of the proposal and/or the project requesting funding. */
+  title?: string;
+
+  /** The description of the proposal and/or the project requesting funding. */
+  description?: string;
+
+  /** The amount of money requested. */
+  amountRequested?: Fields.Money;
+
+  /** The key dates for the project. */
+  projectTimeline?: ProjectTimeline;
+
+  /** The opportunity to which this proposal is related */
+  opportunity?: ProposalOpportunity;
+
+  /** The organization that is requesting funding. */
+  organizations?: ProposalOrgs;
+
+  /** The point of contact for the project. */
+  contacts?: ProposalContacts;
+
+  /** The project's custom fields. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// ProposalOpportunity
+// #########################################################
+
+/** The opportunity to which this proposal is related */
+model ProposalOpportunity {
+  /** The opportunity's unique identifier. */
+  id: Types.uuid;
+
+  /** The opportunity's name. */
+  title?: string;
+
+  /** The opportunity's custom fields. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// ProjectTimeline
+// #########################################################
+
+model ProjectTimeline {
+  /** The start date of the period for which the funding is requested. */
+  startDate?: Fields.Event;
+
+  /** The end date of the period for which the funding is requested. */
+  endDate?: Fields.Event;
+
+  /** The key dates for the project. */
+  otherDates?: Record<Fields.Event>;
+
+  /** Details about the timeline that don't fit into the other fields. */
+  timelineDetails?: string;
+}
+
+// #########################################################
+// ProjectContacts
+// #########################################################
+
+model ProposalContacts {
+  /** The primary point of contact for the proposal. */
+  primary: PersonBase;
+
+  /** Other points of contact for the proposal. For example, key personnel, authorized representatives, etc. */
+  otherContacts?: Record<PersonBase>;
+}
+
+// #########################################################
+// ProposalOrgs
+// #########################################################
+
+model ProposalOrgs {
+  /** The primary organization that is requesting funding. */
+  primary: OrganizationBase;
+
+  /** Other organizations that are supporting the proposal. For example, a fiscal sponsor, partners, etc. */
+  otherOrgs?: Record<OrganizationBase>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Proposal {
+  const exampleProposal = #{
+    title: "Example Project",
+    description: "Example project to serve community needs.",
+    amountRequested: #{ amount: "100000", currency: "USD" },
+    opportunity: exampleOpportunity,
+    projectTimeline: timeline,
+    contacts: contacts,
+    organizations: organizations,
+  };
+
+  // #####################################
+  // Opportunity
+  // #####################################
+
+  const exampleOpportunity = #{
+    id: "083b4567-e89d-42c8-a439-6c1234567890",
+    title: "Example Opportunity",
+    customFields: #{ agency: Fields.Examples.CustomField.agency },
+  };
+
+  // #####################################
+  // ProjectTimeline
+  // #####################################
+
+  const timeline = #{
+    startDate: #{
+      name: "Project Start Date",
+      eventType: Fields.EventType.singleDate,
+      date: Types.isoDate.fromISO("2025-01-01"),
+    },
+    endDate: #{
+      name: "Project End Date",
+      eventType: Fields.EventType.singleDate,
+      date: Types.isoDate.fromISO("2025-12-31"),
+    },
+    otherDates: #{
+      evaluationPeriod: #{
+        name: "Evaluation Period",
+        eventType: Fields.EventType.dateRange,
+        startDate: Types.isoDate.fromISO("2025-07-01"),
+        endDate: Types.isoDate.fromISO("2025-08-31"),
+        description: "The period during which the evaluation will be conducted.",
+      },
+    },
+  };
+
+  // #####################################
+  // Contacts
+  // #####################################
+
+  const contacts = #{
+    primary: Examples.Person.examplePerson,
+    otherContacts: #{
+      principalInvestigator: #{
+        name: #{ prefix: "Dr.", firstName: "Alicia", lastName: "Williams" },
+        emails: #{ primary: "alicia.williams@example.com" },
+      },
+      authorizedRepresentative: #{
+        name: #{ firstName: "John", lastName: "Doe" },
+        emails: #{ primary: "john.doe@example.com" },
+      },
+    },
+  };
+
+  // #####################################
+  // Organizations
+  // #####################################
+
+  const organizations = #{
+    primary: Examples.Organization.exampleOrg,
+    otherOrgs: #{
+      fiscalSponsor: Examples.Organization.exampleOrg,
+      partner: Examples.Organization.exampleOrg,
+    },
+  };
+}

package/lib/core/responses/error.tsp

@@ -28,3 +28,14 @@ model Error {
 
 alias Unauthorized = Error & Http.UnauthorizedResponse;
 alias NotFound = Error & Http.NotFoundResponse;
+
+@example(#{
+  status: 400,
+  message: "Application submission failed due to validation errors",
+  errors: #[#{ field: "formA.name", message: "Name is required" }],
+})
+@doc("A failure to submit an application due to validation errors")
+model ApplicationSubmissionError extends Error {
+  @example(400)
+  status: 400;
+}

package/lib/core/responses/success.tsp

@@ -144,3 +144,19 @@ model Filtered<ItemsT, FilterT> extends Success {
     errors?: string[];
   };
 }
+
+// ############################################################################
+// 201 response
+// ############################################################################
+
+/** A 201 response with data
+ *
+ * @template T The schema for the value of the `"data"` property in this response
+ */
+model Created<T> extends Success {
+  // Inherit the 201 status code
+  ...Http.CreatedResponse;
+
+  /** Response data */
+  data: T;
+}