@common-grants/core 0.1.0-alpha.13 → 0.1.0-alpha.14

package/lib/core/fields/address.tsp

@@ -0,0 +1,86 @@
+namespace CommonGrants.Fields;
+
+/** An mailing address. */
+@example(Examples.Address.apartment)
+model Address {
+  /** The primary street address line. */
+  street1: string;
+
+  /** Additional street address information (e.g., apartment number, suite, etc.). */
+  street2?: string;
+
+  /** The city or municipality name. */
+  city: string;
+
+  /** The state, province, or region name. */
+  stateOrProvince: string;
+
+  /** The country name or ISO country code. */
+  country: string;
+
+  /** The postal or ZIP code for the address. */
+  postalCode: string;
+
+  /** The latitude coordinate of the address location. */
+  latitude?: numeric;
+
+  /** The longitude coordinate of the address location. */
+  longitude?: numeric;
+
+  /** Additional geospatial data in GeoJSON format. */
+  geography?: Record<unknown>;
+}
+
+/** A collection of addresses. */
+@example(Examples.Address.personalCollection)
+@example(Examples.Address.orgCollection)
+model AddressCollection {
+  /** The primary address for a person or organization. */
+  primary: Address;
+
+  /** Additional addresses keyed by a descriptive label (e.g., "work", "home", "international"). */
+  otherAddresses?: Record<Address>;
+}
+
+namespace Examples.Address {
+  const apartment = #{
+    street1: "123 Main St",
+    city: "Anytown",
+    stateOrProvince: "CA",
+    country: "US",
+    postalCode: "12345",
+  };
+
+  const orgAddress = #{
+    street1: "456 Main St",
+    street2: "Suite 100",
+    city: "Anytown",
+    stateOrProvince: "CA",
+    country: "US",
+    postalCode: "12345",
+  };
+
+  const international = #{
+    street1: "123 Rue Principale",
+    city: "Montreal",
+    stateOrProvince: "QC",
+    country: "CA",
+    postalCode: "H2Y 1C6",
+  };
+
+  const personalCollection = #{
+    primary: Examples.Address.apartment,
+    otherAddresses: #{
+      work: Examples.Address.apartment,
+      home: Examples.Address.apartment,
+    },
+  };
+
+  const orgCollection = #{
+    primary: Examples.Address.orgAddress,
+    otherAddresses: #{
+      satellite: Examples.Address.orgAddress,
+      international: Examples.Address.international,
+    },
+  };
+}

package/lib/core/fields/email.tsp

@@ -0,0 +1,35 @@
+import "../types.tsp";
+
+namespace CommonGrants.Fields;
+
+/** An email address. */
+alias Email = Types.email; // Exposes Email from CommonGrants.Fields
+
+/** A collection of email addresses. */
+@example(Examples.Email.personalCollection)
+model EmailCollection {
+  /** The primary email address for a person or organization. */
+  primary: Types.email;
+
+  /** Additional email addresses keyed by a descriptive label (e.g., "work", "personal", "support"). */
+  otherEmails?: Record<Types.email>;
+}
+
+namespace Examples.Email {
+  const personalCollection = #{
+    primary: "john.doe@example.com",
+    otherEmails: #{
+      work: "john.doe@work.com",
+      personal: "john.doe@gmail.com",
+      school: "john.doe@school.edu",
+    },
+  };
+
+  const orgCollection = #{
+    primary: "info@example.com",
+    otherEmails: #{
+      support: "support@example.com",
+      marketing: "marketing@example.com",
+    },
+  };
+}

package/lib/core/fields/index.tsp

@@ -2,6 +2,11 @@ import "./custom-field.tsp";
 import "./metadata.tsp";
 import "./money.tsp";
 import "./event.tsp";
+import "./address.tsp";
+import "./name.tsp";
+import "./phone.tsp";
+import "./pcs.tsp";
+import "./email.tsp";
 
 using TypeSpec.JsonSchema;
 

package/lib/core/fields/name.tsp

@@ -0,0 +1,30 @@
+namespace CommonGrants.Fields;
+
+/** A person's name. */
+@example(Examples.Name.janeDoe)
+model Name {
+  /** Honorific prefix (e.g., Mr., Mrs., Dr., Prof.). */
+  prefix?: string;
+
+  /** The person's first or given name. */
+  firstName: string;
+
+  /** The person's middle name or names. */
+  middleName?: string;
+
+  /** The person's last name or family name. */
+  lastName: string;
+
+  /** Name suffix (e.g., Jr., Sr., III, Ph.D.). */
+  suffix?: string;
+}
+
+namespace Examples.Name {
+  const janeDoe = #{
+    prefix: "Dr.",
+    firstName: "Jane",
+    middleName: "Edward",
+    lastName: "Doe",
+    suffix: "Jr.",
+  };
+}

package/lib/core/fields/pcs.tsp

@@ -0,0 +1,112 @@
+namespace CommonGrants.Fields;
+
+/** A Philanthropy Classification System (PCS) term.
+ *
+ * The PCS is a hierarchical classification system for categorizing data related to
+ * philanthropic activities. It supports the following classes:
+ * - Organization types
+ * - Subjects
+ * - Population groups
+ * - Transaction types
+ * - Support strategies
+ *
+ * See https://taxonomy.candid.org/ for more information.
+ */
+@example(Examples.PCS.orgTypeTerm)
+model PCSTerm {
+  /** The plain language PCS term. */
+  term: string;
+
+  /** The class to which the PCS term belongs. */
+  class: PCSClass;
+
+  /** The code for this PCS term. */
+  @pattern("[A-Z]{2}[0-9]{6}")
+  @example("UC0")
+  code: string;
+
+  /** Description of the PCS term */
+  description?: string;
+}
+
+// #########################################################
+// PCSClass
+// #########################################################
+
+/** The class to which the PCS term belongs. */
+enum PCSClass {
+  orgTypes: "Organization types",
+  subjects: "Subjects",
+  populationGroups: "Population groups",
+  transactionTypes: "Transaction types",
+  supportStrategies: "Support strategies",
+}
+
+// #########################################################
+// PCS class types
+// #########################################################
+
+/** A Philanthropy Classification System (PCS) term for organization types.
+ *
+ * See https://taxonomy.candid.org/organization-type for more information.
+ */
+model PCSOrgType extends PCSTerm {
+  /** The PCS term for the organization type. */
+  class: PCSClass.orgTypes;
+}
+
+/** A Philanthropy Classification System (PCS) term for the subject of the grant.
+ *
+ * See https://taxonomy.candid.org/subjects for more information.
+ */
+model PCSSubject extends PCSTerm {
+  /** The PCS term for the subject. */
+  class: PCSClass.subjects;
+}
+
+/** A Philanthropy Classification System (PCS) term for populations served.
+ *
+ * See https://taxonomy.candid.org/populations for more information.
+ */
+model PCSPopulation extends PCSTerm {
+  /** The PCS term for the population. */
+  class: PCSClass.populationGroups;
+}
+
+/** A Philanthropy Classification System (PCS) term for support strategies.
+ *
+ * See https://taxonomy.candid.org/support-strategies for more information.
+ */
+model PCSSupportStrategy extends PCSTerm {
+  /** The PCS term for the support strategy. */
+  class: PCSClass.supportStrategies;
+}
+
+/** A Philanthropy Classification System (PCS) term for transaction types.
+ *
+ * See https://taxonomy.candid.org/transaction-types for more information.
+ */
+model PCSTransactionType extends PCSTerm {
+  /** The PCS term for the transaction type. */
+  class: PCSClass.transactionTypes;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.PCS {
+  const orgTypeTerm = #{
+    term: "Hospital",
+    class: PCSClass.orgTypes,
+    description: "Institutions with the primary purpose of providing in-patient physical and mental health services...",
+    code: "EO000000",
+  };
+
+  const subjectTerm = #{
+    term: "Education",
+    class: PCSClass.subjects,
+    description: "All formally constituted educational institutions (except art and performing art schools) and projects or activities...",
+    code: "SB000000",
+  };
+}

package/lib/core/fields/phone.tsp

@@ -0,0 +1,65 @@
+namespace CommonGrants.Fields;
+
+/** A phone number. */
+@example(Examples.Phone.mobile)
+@example(Examples.Phone.withExtension)
+model Phone {
+  /** The international country code (e.g., "+1" for US/Canada). */
+  @pattern("^\\+[1-9][0-9]{1,3}$")
+  countryCode: string;
+
+  /** The local phone number without the country code. */
+  number: string;
+
+  /** Optional extension number for the phone line. */
+  extension?: string;
+
+  /** Indicates whether this is a mobile/cell phone number. */
+  isMobile?: boolean = false;
+}
+
+// #########################################################
+// Phone Collection
+// #########################################################
+
+/** A collection of phone numbers for a person. */
+@example(Examples.Phone.personalCollection)
+@example(Examples.Phone.orgCollection)
+model PhoneCollection {
+  /** The person's primary phone number. */
+  primary: Fields.Phone;
+
+  /** The person's fax number, if applicable. */
+  fax?: Fields.Phone;
+
+  /** Additional phone numbers not covered by the standard fields. */
+  otherPhones?: Record<Fields.Phone>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Phone {
+  const mobile = #{ countryCode: "+1", number: "444-456-1230", isMobile: true };
+
+  const home = #{ countryCode: "+1", number: "333-456-1230", isMobile: false };
+
+  const withExtension = #{
+    countryCode: "+1",
+    number: "555-123-4567",
+    extension: "123",
+    isMobile: false,
+  };
+
+  const personalCollection = #{ primary: mobile, otherPhones: #{ home: home } };
+
+  const orgCollection = #{
+    primary: mobile,
+    fax: withExtension,
+    otherPhones: #{
+      support: #{ countryCode: "+1", number: "333-456-1230", isMobile: false },
+      marketing: #{ countryCode: "+1", number: "444-456-1230", isMobile: true },
+    },
+  };
+}

package/lib/core/models/application.tsp

@@ -0,0 +1,142 @@
+import "../index.tsp";
+
+namespace CommonGrants.Models;
+
+/** The base model for an application. */
+@example(Examples.Application.exampleApplication)
+model ApplicationBase {
+  /** The application's unique identifier. */
+  id: Types.uuid;
+
+  /** The application's status. */
+  status?: AppStatus;
+
+  /** The application's date of submission. */
+  dateSubmitted?: Types.isoDate;
+
+  /** The organization that is applying for the grant. */
+  organization?: OrganizationBase;
+
+  /** The person who is applying for the grant. */
+  pointOfContact?: PersonBase;
+
+  /** The application's proposal for funding. */
+  proposal?: AppProposal;
+
+  /** The opportunity being applied to. */
+  opportunity?: AppOpportunity;
+
+  /** The application's custom fields. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// AppStatus
+// #########################################################
+
+/** The status of the application. */
+@example(Examples.Application.submittedStatus)
+model AppStatus {
+  /** The status of the application. */
+  value: AppStatusOptions;
+
+  /** A custom value for the status. */
+  customValue?: string;
+
+  /** A description of the status. */
+  description?: string;
+}
+
+// #########################################################
+// AppStatusOptions
+// #########################################################
+
+/** The default set of values accepted for application status. */
+enum AppStatusOptions {
+  submitted,
+  approved,
+  rejected,
+  custom,
+}
+
+// #########################################################
+// AppProject
+// #########################################################
+
+/** The project for which funding is requested. */
+@example(Examples.Application.exampleProposal)
+model AppProposal {
+  /** 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 start date of the period for which the funding is requested. */
+  periodStartDate?: Types.isoDate;
+
+  /** The end date of the period for which the funding is requested. */
+  periodEndDate?: Types.isoDate;
+
+  /** The project's custom fields. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// AppOpportunity
+// #########################################################
+
+/** The opportunity to which this application is related */
+model AppOpportunity {
+  /** The opportunity's unique identifier. */
+  id: Types.uuid;
+
+  /** The opportunity's name. */
+  title?: string;
+
+  /** The opportunity's custom fields. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Application {
+  const exampleApplication = #{
+    id: "083b4567-e89d-42c8-a439-6c1234567890",
+    status: submittedStatus,
+    dateSubmitted: Types.isoDate.fromISO("2024-01-01"),
+    organization: Examples.Organization.exampleOrg,
+    pointOfContact: Examples.Person.examplePerson,
+    proposal: exampleProposal,
+    opportunity: exampleOpportunity,
+  };
+
+  const submittedStatus = #{
+    value: AppStatusOptions.submitted,
+    description: "Application has been submitted.",
+  };
+
+  const customStatus = #{
+    value: AppStatusOptions.custom,
+    customValue: "draft",
+    description: "Application is started but not yet submitted.",
+  };
+
+  const exampleProposal = #{
+    title: "Example Project",
+    description: "Example project to serve community needs.",
+    amountRequested: #{ amount: "100000", currency: "USD" },
+    periodStartDate: Types.isoDate.fromISO("2024-01-01"),
+    periodEndDate: Types.isoDate.fromISO("2024-12-31"),
+  };
+
+  const exampleOpportunity = #{
+    id: "083b4567-e89d-42c8-a439-6c1234567890",
+    title: "Example Opportunity",
+  };
+}

package/lib/core/models/index.tsp

@@ -3,6 +3,9 @@ import "@typespec/json-schema";
 // Import individual schemas to provide a consistent interface
 // and make them available throughout the namespace
 import "./opportunity/index.tsp";
+import "./organization.tsp";
+import "./person.tsp";
+import "./application.tsp";
 
 using TypeSpec.JsonSchema;
 

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). */
+  type?: 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",
+    type: 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/types.tsp

@@ -29,6 +29,11 @@ scalar isoTime extends plainTime;
 @example(isoDate.fromISO("2025-01-01"))
 scalar isoDate extends plainDate;
 
+/** A calendar year */
+@example("2025")
+@pattern("^[0-9]{4}$")
+scalar calendarYear extends string;
+
 /** A universally unique identifier */
 @example("30a12e5e-5940-4c08-921c-17a8960fcf4b")
 @format("uuid")
@@ -43,3 +48,23 @@ scalar uuid extends string;
 @example("100.5", #{ title: "Scale 1" })
 @example("-100.5", #{ title: "Negative, scale 2" })
 scalar decimalString extends string;
+
+/** An email address */
+@example("test@example.com")
+@format("email")
+scalar email extends string;
+
+/** An Employer Identification Number (EIN) */
+@example("123456789")
+@pattern("^[0-9]{2}-[0-9]{7}$")
+scalar employerTaxId extends string;
+
+/** A Unique Entity Identifier (UEI) */
+@example("ABC1234567890")
+@pattern("^[A-z0-9]{12}$")
+scalar samUEI extends string;
+
+/** A Data Universal Numbering System (DUNS) number */
+@example("123456789012")
+@pattern("^[0-9]{9}$")
+scalar duns extends string;

package/package.json

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