@common-grants/core 0.1.0-alpha.4

package/README.md

@@ -0,0 +1,66 @@
+# Simpler grant protocol specifications
+
+Code for the simpler grant protocol base specification libraries, written in TypeSpec. They are designed to be imported and extended by individual implementations of the grant protocol.
+
+## 🚀 Project Structure
+
+The `specs/` sub-directory is organized like this:
+
+```
+.
+├── lib/                # Defines reusable models and routes for the library
+│   ├── models/         # Defines base models like Opportunity, CustomField, etc.
+│   ├── routes/         # Defines base routes like GET /opportunities
+│   └── main.tsp        # Exposes models and routes from the root of the library
+|
+├── src/
+│   ├── index.ts        # Defines the entry point for the library
+│   └── lib.ts          # Creates a new TypeSpec library definition
+|
+├── dist/               # .gitignored directory that stores the output of `npm build`
+|
+├── package.json        # Manages dependencies, commands, and library metadata
+├── tsconfig.json       # Manages TypeScript configuration
+└── tspconfig.yaml      # Manages TypeSpec configuration
+```
+
+## 💻 Local development
+
+### Pre-requisites
+
+Node version 20 or later. Check with `node --version`
+
+### Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                | Action                                     |
+| :--------------------- | :----------------------------------------- |
+| `npm install`          | Installs dependencies                      |
+| `npm run build`        | Build package locally                      |
+| `npm pack`             | Create a tarball from the package          |
+| `npm typespec`         | Compile and emit the library with TypeSpec |
+| `npm run format`       | Run automatic formatting and fix issues    |
+| `npm run lint`         | Run automatic linting and fix issues       |
+| `npm run check:format` | Check formatting, fail if issues are found |
+| `npm run check:lint`   | Check linting, fail if issues are found    |
+
+### Installing the library locally
+
+The medium-term goal is to publish this library to npm so that it can be installed directly using `npm install`. For the interim, however, you can install the library locally by running the following steps from the root of this directory:
+
+1. Build the library: `npm build`
+2. Package the library as a tarball: `npm pack`
+3. Change directory into the node project where you want to install this library: `cd $path_to_other_project`
+4. Add the following to that project's `package.json` (replacing the values between the angled brackets `<>`):
+   ```json
+   "peerDependencies": {
+       "@typespec/compiler": "^0.63.0",
+       "@common-grants/core": "file:<relative-path-to-library>/common-grants-core-<version>.tgz"
+   },
+   ```
+5. Then run `npm install` to install this package
+
+### Using the library
+
+Check out the [Custom API codebase](../examples/custom-api/) for an example of how to use this library within your own project. A more detailed tutorial is in the works.

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { $lib } from "./lib.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -0,0 +1,3 @@
+// Re-export $lib so the compiler can access it and register your library correctly
+export { $lib } from "./lib.js";
+//# sourceMappingURL=index.js.map

package/dist/src/lib.d.ts

@@ -0,0 +1,13 @@
+export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}, Record<string, any>, never>;
+export declare const reportDiagnostic: <C extends string | number, M extends keyof {
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}[C]>(program: import("@typespec/compiler").Program, diag: import("@typespec/compiler").DiagnosticReport<{
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}, C, M>) => void, createDiagnostic: <C extends string | number, M extends keyof {
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}[C]>(diag: import("@typespec/compiler").DiagnosticReport<{
+    [code: string]: import("@typespec/compiler").DiagnosticMessages;
+}, C, M>) => import("@typespec/compiler").Diagnostic;
+//# sourceMappingURL=lib.d.ts.map

package/dist/src/lib.js

@@ -0,0 +1,10 @@
+import { createTypeSpecLibrary } from "@typespec/compiler";
+export const $lib = createTypeSpecLibrary({
+    name: "@common-grants/core",
+    diagnostics: {
+    // We'll add diagnostics later if needed
+    },
+});
+// Optional but convenient, these are meant to be used locally in your library
+export const { reportDiagnostic, createDiagnostic } = $lib;
+//# sourceMappingURL=lib.js.map

package/lib/main.tsp

@@ -0,0 +1,11 @@
+// Import the JS entry point for this library
+// For more details see:
+// https://typespec.io/docs/extending-typespec/basics/#h-add-your-main-typespec-file
+import "../dist/src/index.js";
+
+// Import Models and Routes to make them available outside the package
+import "./models/index.tsp";
+import "./routes/index.tsp";
+
+// Define the top-level namespace for the library
+namespace CommonGrants;

package/lib/models/base.tsp

@@ -0,0 +1,24 @@
+namespace CommonGrants.Models;
+
+/** A time on a clock, without a timezone, in ISO 8601 format HH:mm:ss */
+@example(isoTime.fromISO("17:00:00"))
+scalar isoTime extends plainTime;
+
+/** A date on a calendar in ISO 8601 format YYYY-MM-DD */
+@example(isoDate.fromISO("2025-01-01"))
+scalar isoDate extends plainTime;
+
+/** A universally unique identifier */
+@example("30a12e5e-5940-4c08-921c-17a8960fcf4b")
+@format("uuid")
+scalar uuid extends string;
+
+/** A decimal number (with variable scale) encoded as a string, to avoid floating point issues */
+@pattern(
+    "^-?[0-9]+\\.?[0-9]*$",
+    "Must be a valid decimal number represented as a string"
+)
+@example("100", #{ title: "Scale 0" })
+@example("100.5", #{ title: "Scale 1" })
+@example("-100.5", #{ title: "Negative, scale 2" })
+scalar decimalString extends string;

package/lib/models/custom-field.tsp

@@ -0,0 +1,62 @@
+namespace CommonGrants.Models;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** The set of JSON schema types supported by a custom field */
+enum CustomFieldType {
+  string,
+  number,
+  boolean,
+  object,
+  array,
+}
+
+@example(
+  CustomFieldExamples.programArea,
+  #{ title: "String field for program area" }
+)
+@example(
+  CustomFieldExamples.eligibilityTypes,
+  #{ title: "Array field for eligibility types" }
+)
+model CustomField {
+  /** Name of the custom field */
+  name: string;
+
+  /** The JSON schema type to use when de-serializing the `value` field */
+  type: CustomFieldType;
+
+  /** Link to the full JSON schema for this custom field */
+  schema?: url;
+
+  /** Value of the custom field */
+  value: unknown;
+
+  /** Description of the custom field's purpose */
+  description?: string;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+namespace CustomFieldExamples {
+  /** An example of a string custom field */
+  const programArea = #{
+    name: "programArea",
+    type: CustomFieldType.string,
+    value: "Healthcare Innovation",
+    description: "Primary focus area of the grant program",
+    schema: "https://example.com/program-areas.json",
+  };
+
+  /** An example of an array custom field */
+  const eligibilityTypes = #{
+    name: "eligibilityType",
+    type: CustomFieldType.array,
+    value: #["nonprofit", "academic"],
+    description: "Types of eligible organizations",
+  };
+}

package/lib/models/event.tsp

@@ -0,0 +1,42 @@
+namespace CommonGrants.Models;
+
+// ########################################
+// Model definition
+// ########################################
+
+@example(EventExamples.deadline, #{ title: "Application deadline with time" })
+@example(EventExamples.openDate, #{ title: "Opening date without time" })
+model Event {
+  /** Name of the timeline event (e.g., 'Open Date', 'Deadline') */
+  name: string;
+
+  /** Date of the event in in ISO 8601 format: YYYY-MM-DD */
+  date: isoDate;
+
+  /** Time of the event in ISO 8601 format: HH:MM:SS */
+  time?: isoTime;
+
+  /** Detailed description of the timeline event */
+  description?: string;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+namespace EventExamples {
+  /** An example of a deadline event with a specific time */
+  const deadline = #{
+    name: "Application Deadline",
+    date: isoDate.fromISO("2024-12-31"),
+    time: isoTime.fromISO("17:00:00"),
+    description: "Final submission deadline for all grant applications",
+  };
+
+  /** An example of an opening date without a specific time */
+  const openDate = #{
+    name: "Open Date",
+    date: isoDate.fromISO("2024-01-15"),
+    description: "Applications begin being accepted",
+  };
+}

package/lib/models/funding.tsp

@@ -0,0 +1,55 @@
+using TypeSpec.Http;
+
+namespace CommonGrants.Models;
+
+// ########################################
+// Model definition
+// ########################################
+
+@example(FundingExamples.allFields, #{ title: "All fields defined" })
+@example(
+  FundingExamples.awardRange,
+  #{ title: "Award range but no total limit" }
+)
+@example(
+  FundingExamples.onlyLimit,
+  #{ title: "Total funding limit but no award range" }
+)
+model FundingDetails {
+  totalAmountAvailable?: Money;
+  minAwardAmount?: Money;
+  maxAwardAmount?: Money;
+  minAwardCount?: integer;
+  maxAwardCount?: integer;
+  estimatedAwardCount?: integer;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+namespace FundingExamples {
+  /** A FundingDetails example in which all of the fields are defined */
+  const allFields = #{
+    totalAmountAvailable: #{ amount: "1000000.00", currency: "USD" },
+    minAwardAmount: #{ amount: "10000.00", currency: "USD" },
+    maxAwardAmount: #{ amount: "50000.00", currency: "USD" },
+    minAwardCount: 5,
+    maxAwardCount: 20,
+    estimatedAwardCount: 10,
+  };
+
+  /** A FundingDetails example that has an award range but no total limit */
+  const awardRange = #{
+    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 */
+  const onlyLimit = #{
+    totalAmountAvailable: #{ amount: "1000000.00", currency: "USD" },
+    estimatedAwardCount: 10,
+  };
+}

package/lib/models/index.tsp

@@ -0,0 +1,17 @@
+import "@typespec/json-schema";
+
+// Import individual models to provide a consistent interface
+// and make them available throughout the namespace
+import "./base.tsp";
+import "./custom-field.tsp";
+import "./money.tsp";
+import "./funding.tsp";
+import "./event.tsp";
+import "./opportunity.tsp";
+
+using TypeSpec.JsonSchema;
+
+// Define the top-level namespace for the models
+// and emit these models as JSON schemas
+@jsonSchema
+namespace CommonGrants.Models;

package/lib/models/money.tsp

@@ -0,0 +1,37 @@
+namespace CommonGrants.Models;
+
+// ########################################
+// Model definition
+// ########################################
+
+@example(MoneyExamples.usdWithCents, #{ title: "US dollars and cents" })
+@example(
+  MoneyExamples.euroWithoutCents,
+  #{ title: "Euros displayed without cents" }
+)
+@example(
+  MoneyExamples.usdNegative,
+  #{ title: "A negative amount of US dollars and cents" }
+)
+model Money {
+  /** The amount of money */
+  amount: decimalString;
+
+  /** The ISO 4217 currency code in which the amount is denominated */
+  currency: string;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+namespace MoneyExamples {
+  /** An example of a positive USD amount with cents */
+  const usdWithCents = #{ amount: "10000.50", currency: "USD" };
+
+  /** An example of a positive EUR amount without cents */
+  const euroWithoutCents = #{ amount: "5000", currency: "EUR" };
+
+  /** An example of a negative USD amount in accounting format */
+  const usdNegative = #{ amount: "-50.50", currency: "USD" };
+}

package/lib/models/opportunity.tsp

@@ -0,0 +1,65 @@
+namespace CommonGrants.Models;
+
+// ########################################
+// Model definition
+// ########################################
+
+@example(
+  OpportunityExamples.complete,
+  #{ title: "Complete opportunity with all fields" }
+)
+@example(
+  OpportunityExamples.minimal,
+  #{ title: "Minimal opportunity with required fields only" }
+)
+model Opportunity {
+  /** Globally unique id for the opportunity */
+  id: uuid;
+
+  /** URL for the original source of the opportunity */
+  source: url;
+
+  /** Title or name of the funding opportunity */
+  title: string;
+
+  /** Description of the opportunity's purpose and scope */
+  description: string;
+
+  /** Details about the funding available */
+  fundingDetails: FundingDetails;
+
+  /** Key dates and milestones in the application process */
+  applicationTimeline?: Event[];
+
+  /** Additional custom fields specific to this opportunity */
+  customFields?: Record<CustomField>;
+}
+
+// ########################################
+// 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,
+    applicationTimeline: #[EventExamples.openDate, EventExamples.deadline],
+    customFields: #{
+      programArea: CustomFieldExamples.programArea,
+      eligibilityType: CustomFieldExamples.programArea,
+    },
+  };
+
+  /** 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,
+  };
+}

package/lib/routes/index.tsp

@@ -0,0 +1,8 @@
+import "@typespec/http";
+import "@typespec/rest";
+
+// Import individual route files to provide a consistent interface
+import "./opportunities.tsp";
+
+// Define the
+namespace CommonGrants.Routes;

package/lib/routes/opportunities.tsp

@@ -0,0 +1,23 @@
+import "../models/index.tsp";
+
+// Define the top-level namespace for CommonGrants routes
+namespace CommonGrants.Routes;
+
+// Expose the contents of the Http and Rest namespaces
+// these include the decorators @route, @get, etc.
+using TypeSpec.Http;
+using TypeSpec.Rest;
+
+// Define the `/opportunities` router
+@route("/opportunities")
+interface Opportunities {
+  @summary("List opportunities")
+  @doc("Get a list of opportunities")
+  @get
+  list(): Models.Opportunity[];
+
+  @summary("View opportunity")
+  @doc("View additional details about an opportunity")
+  @get
+  read(@path title: string): Models.Opportunity;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@common-grants/core",
+  "version": "0.1.0-alpha.4",
+  "description": "TypeSpec library for defining grant opportunity data models and APIs",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "typespec": "./lib/main.tsp",
+      "default": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/src/**/*.js",
+    "dist/src/**/*.d.ts",
+    "lib/**/*.tsp",
+    "!src/**/*.test.*"
+  ],
+  "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"
+  },
+  "keywords": [
+    "typespec",
+    "api",
+    "grants",
+    "opportunities"
+  ],
+  "author": "CommonGrants",
+  "license": "CC0-1.0",
+  "peerDependencies": {
+    "@typespec/compiler": "^0.63.0",
+    "@typespec/http": "^0.63.0",
+    "@typespec/json-schema": "^0.63.0",
+    "@typespec/openapi3": "^0.63.0",
+    "@typespec/rest": "^0.63.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.6",
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.2",
+    "rimraf": "^5.0.5",
+    "source-map-support": "^0.5.21",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.20.0"
+  }
+}