@common-grants/core 0.1.0-alpha.10

package/lib/core/routes/opportunities.tsp

@@ -0,0 +1,98 @@
+import "../models/index.tsp";
+import "../responses/index.tsp";
+import "../pagination.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;
+
+/** A re-usable interface for an Opportunities router
+ *
+ * To implement this interface, we recommend declaring a namespace,
+ * instantiating the router using `alias` (instead of `extends`),
+ * and decorating the namespace with `@route` and `@tag` since they aren't
+ * inherited directly from the interface.
+ *
+ * For more information, see
+ * [TypeSpec docs](https://typespec.io/docs/language-basics/interfaces/#templating-interface-operations)
+ *
+ * @example Using the the default type for the list operation and
+ * a custom model for the read operation:
+ * ```typespec
+ * using TypeSpec.Http;
+ *
+ * @tag("Opportunities")
+ * @route("/opportunities/")
+ * namespace Opportunities {
+ *   alias Router = Routes.Opportunities
+ *
+ *   op list is Router.list;
+ *   op read is Router.read<CustomOpportunity>;
+ * }
+ * ```
+ */
+interface Opportunities {
+  // ###############################
+  // List opportunities
+  // ###############################
+
+  /** `GET /opportunities/` Get a paginated list of opportunities
+   *
+   * @template T Type of the paginated response model.
+   * Must be an extension of Schemas.OpportunityBase. Default is Schemas.OpportunityBase.
+   */
+  @summary("List opportunities")
+  @doc("Get a paginated list of opportunities, sorted by `lastModifiedAt` with most recent first.")
+  @list
+  list<T extends Models.OpportunityBase = Models.OpportunityBase>(
+    ...Pagination.PaginatedQueryParams,
+  ): Responses.Paginated<T> | Responses.Unauthorized;
+
+  // ##############################
+  // View an opportunity
+  // ##############################
+
+  /** `GET /opportunities/<id>` View opportunity details
+   *
+   * @template T Type of the response model.
+   * Must be an extension of Schemas.OpportunityBase. Default is Schemas.OpportunityBase.
+   */
+  @summary("View opportunity")
+  @doc("View additional details about an opportunity")
+  @get
+  read<T extends Models.OpportunityBase = Models.OpportunityBase>(
+    /** The ID of the opportunity to view */
+    @path id: Types.uuid,
+  ): Responses.Ok<T> | Responses.NotFound | Responses.Unauthorized;
+
+  // ###############################
+  // Search opportunities
+  // ###############################
+
+  /** `POST /opportunities/search` Search opportunities
+   *
+   * @template T Type of the response model.
+   * Must be an extension of Schemas.OpportunityBase. Default is Schemas.OpportunityBase.
+   */
+  @summary("Search opportunities")
+  @doc("Search for opportunities based on the provided filters")
+  @post
+  @route("/search")
+  search<T extends Models.OpportunityBase = Models.OpportunityBase>(
+    /** Filters to apply to the opportunity search
+     *
+     * Multiple filter conditions will be combined with AND logic, so that
+     * results only include opportunities that match all of the provided filters.
+     */
+    filters?: Models.OppFilters,
+
+    /** The sort order to apply to the results */
+    sorting?: Models.OppSorting,
+
+    /** Pagination instructions for the results */
+    pagination?: Pagination.PaginatedBodyParams,
+  ): Responses.Filtered<T, Models.OppFilters> | Responses.Unauthorized;
+}

package/lib/core/sorting.tsp

@@ -0,0 +1,71 @@
+import "@typespec/http";
+
+using TypeSpec.Http;
+
+/** Models for sorting
+ *
+ * @example How to use the `Sorting` namespace
+ * ```typespec
+ *
+ * using CommonGrants // Exposes the `Sorting` and `Responses` namespaces
+ * using TypeSpec.Http;
+ *
+ * @route("/foo/")
+ * @get
+ * op list(sorting: Sorting.SortQueryParams): Responses.Sorted<MyModel>;
+ * ```
+ */
+namespace CommonGrants.Sorting;
+
+enum SortOrder {
+  asc,
+  desc,
+}
+
+/** Query parameters for sorting */
+model SortQueryParams {
+  /** The field to sort by */
+  @query
+  @example("lastModifiedAt")
+  sortBy: string;
+
+  /** Implementation-defined sort key */
+  @query
+  @example("customField")
+  customSortBy?: string;
+
+  /** The order to sort by */
+  @query
+  @example(SortOrder.asc)
+  sortOrder?: SortOrder;
+}
+
+/** Sorting parameters included in the request body */
+model SortBodyParams {
+  /** The field to sort by */
+  @example("lastModifiedAt")
+  sortBy: unknown;
+
+  /** Implementation-defined sort key */
+  @example("customField")
+  customSortBy?: string;
+
+  /** The order to sort by */
+  @example(SortOrder.asc)
+  sortOrder?: SortOrder;
+}
+
+/** Information about the sort order of the items returned */
+model SortInfo {
+  /** The field to sort by */
+  @example("lastModifiedAt")
+  sortBy: string;
+
+  /** Implementation-defined sort key */
+  @example("customField")
+  customSortBy?: string;
+
+  /** The order to sort by */
+  @example(SortOrder.asc)
+  sortOrder?: SortOrder;
+}

package/lib/core/types.tsp

@@ -0,0 +1,42 @@
+/** A collection of base data types used throughout the CommonGrants API
+ *
+ * @example How to use the `Types` namespace
+ *
+ * ```typespec
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Types namespace
+ *
+ * model MyModel {
+ *   @example("30a12e5e-5940-4c08-921c-17a8960fcf4b")
+ *   id: Types.uuid;
+ *
+ *   @example(Types.isoDate.fromISO("2025-01-01"))
+ *   keyDate: Types.isoDate;
+ * }
+ * ```
+ */
+namespace CommonGrants.Types;
+
+/** 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 plainDate;
+
+/** 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/main.tsp

@@ -0,0 +1,9 @@
+// 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 "./core/index.tsp";
+import "./api.tsp";
+
+namespace CommonGrants;

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@common-grants/core",
+  "version": "0.1.0-alpha.10",
+  "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.*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HHS/simpler-grants-protocol.git",
+    "directory": "specs"
+  },
+  "bugs": {
+    "url": "https://github.com/HHS/simpler-grants-protocol/issues"
+  },
+  "homepage": "https://github.com/HHS/simpler-grants-protocol/tree/main/specs#readme",
+  "scripts": {
+    "prepublishOnly": "bash scripts/prepublish-checks.sh",
+    "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",
+    "docs:build": "npx @redocly/cli build-docs tsp-output/@typespec/openapi3/openapi.yaml --output ./dist/redocly.html",
+    "docs:preview": "open ./dist/redocly.html",
+    "docs": "npm run typespec && npm run docs:build && npm run docs:preview"
+  },
+  "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"
+  }
+}