@common-grants/core 0.1.0-alpha.7 → 0.1.0-alpha.8

package/lib/api.tsp

@@ -0,0 +1,29 @@
+// Import Schemas.and Routes to make them available outside the package
+import "./core/index.tsp";
+import "@typespec/http";
+
+using Core;
+
+using TypeSpec.Http;
+
+/** The base OpenAPI specification for a CommonGrants API
+ *
+ * In order for an API to be "compliant" with the CommonGrants protocol,
+ * it must implement all of the routes with the "required" tag in this specification.
+ */
+@service({
+  title: "CommonGrants Base API",
+})
+namespace CommonGrants.API;
+
+@tag("Opportunities")
+@route("/opportunities")
+namespace Opportunities {
+  alias Router = Routes.Opportunities;
+
+  @tag("required")
+  op List is Router.list;
+
+  @tag("required")
+  op Read is Router.read;
+}

package/lib/{models → core/fields}/custom-field.tsp

@@ -1,4 +1,4 @@
-namespace CommonGrants.Models;
+namespace Core.Fields;
 
 // ########################################
 // Field types definition
@@ -14,7 +14,7 @@ enum CustomFieldType {
 }
 
 // ########################################
-// Models definition
+// Model definition
 // ########################################
 
 /** Model for defining custom fields that are specific to a given implementation.

package/lib/{models → core/fields}/event.tsp

@@ -1,4 +1,8 @@
-namespace CommonGrants.Models;
+import "../types.tsp";
+
+namespace Core.Fields;
+
+using Core.Types;
 
 // ########################################
 // Model definition

package/lib/core/fields/index.tsp

@@ -0,0 +1,6 @@
+import "./custom-field.tsp";
+import "./metadata.tsp";
+import "./money.tsp";
+import "./event.tsp";
+
+namespace Internals.Schemas.Fields;

package/lib/{models → core/fields}/metadata.tsp

@@ -1,4 +1,4 @@
-namespace CommonGrants.Models;
+namespace Core.Fields;
 
 // ########################################
 // Model definition

package/lib/{models → core/fields}/money.tsp

@@ -1,4 +1,8 @@
-namespace CommonGrants.Models;
+import "../types.tsp";
+
+namespace Core.Fields;
+
+using Core.Types;
 
 // ########################################
 // Model definition

package/lib/core/index.tsp

@@ -0,0 +1,8 @@
+import "./types.tsp";
+import "./fields/index.tsp";
+import "./models/index.tsp";
+import "./routes/index.tsp";
+import "./responses/index.tsp";
+
+/** An internal namespace for the `@common-grants/core` package */
+namespace Core;

package/lib/{models → core/models}/index.tsp

@@ -1,20 +1,14 @@
 import "@typespec/json-schema";
 
-// Import individual models to provide a consistent interface
+// Import individual schemas to provide a consistent interface
 // and make them available throughout the namespace
-import "./base.tsp";
-import "./custom-field.tsp";
-import "./money.tsp";
-import "./event.tsp";
-import "./metadata.tsp";
-import "./custom-enum.tsp";
 import "./opportunity/index.tsp";
 
 using TypeSpec.JsonSchema;
 
-/** Namespace for CommonGrants models that can be used in API routes */
-@jsonSchema // and emit these models as JSON schemas
-namespace CommonGrants.Models;
+/** Namespace for Core that can be used in API routes */
+@jsonSchema // and emit these Schemas.as JSON schemas
+namespace Core.Models;
 
 /** The base model for a funding opportunity.
  *
@@ -23,6 +17,9 @@ namespace CommonGrants.Models;
  * @example How to declare a new Opportunity model with custom fields
  *
  * ```typespec
+ * using Core.Fields;
+ * using Core.Models;
+ *
  * model Agency extends CustomField {
  *   type: CustomFieldType.string;
  *

package/lib/{models/opportunity/index.tsp → core/models/opportunity/base.tsp}

@@ -1,12 +1,14 @@
-import "@typespec/json-schema";
-
 import "./status.tsp";
 import "./funding.tsp";
 import "./timeline.tsp";
+import "../../fields/index.tsp";
+import "../../types.tsp";
+
+/** Namespace for Core that are specific to funding opportunities */
+namespace Core.Models.Opportunity;
 
-/** Namespace for CommonGrants models that are specific to funding opportunities */
-@JsonSchema.jsonSchema
-namespace CommonGrants.Models.Opportunity;
+using Core.Fields;
+using Core.Types;
 
 // ########################################
 // Model definition

package/lib/{models → core/models}/opportunity/funding.tsp

@@ -1,6 +1,9 @@
 import "../index.tsp";
+import "../../fields/index.tsp";
 
-namespace CommonGrants.Models.Opportunity;
+namespace Core.Models.Opportunity;
+
+using Core.Fields;
 
 // ########################################
 // Model definition

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

@@ -0,0 +1,6 @@
+import "./status.tsp";
+import "./funding.tsp";
+import "./timeline.tsp";
+import "./base.tsp";
+
+namespace Core.Models.Opportunity;

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

@@ -0,0 +1,32 @@
+import "@typespec/json-schema";
+import "@typespec/openapi3";
+
+namespace Core.Models.Opportunity;
+
+// ########################################
+// Opportunity status options
+// ########################################
+
+/** The set of values accepted for opportunity status */
+enum OppStatusOptions {
+  forecasted,
+  open,
+  closed,
+  custom,
+}
+
+// ########################################
+// Opportunity status model
+// ########################################
+
+/** The status of the opportunity */
+model OppStatus {
+  /** The status value */
+  value: OppStatusOptions;
+
+  /** A custom status value */
+  customValue?: string;
+
+  /** A human-readable description of the status */
+  description?: string;
+}

package/lib/{models → core/models}/opportunity/timeline.tsp

@@ -1,7 +1,10 @@
-import "../event.tsp";
-import "../custom-enum.tsp";
+import "../../fields/index.tsp";
+import "../../types.tsp";
 
-namespace CommonGrants.Models.Opportunity;
+namespace Core.Models.Opportunity;
+
+using Core.Fields;
+using Core.Types;
 
 // ########################################
 // Model definition

package/lib/{responses/errors.tsp → core/responses/error.tsp}

@@ -1,4 +1,6 @@
-namespace Responses.Error;
+import "@typespec/http";
+
+namespace Core.Responses;
 
 /** A standard error response schema, used to create custom error responses
  *

package/lib/{responses → core/responses}/index.tsp

@@ -1,6 +1,6 @@
 import "@typespec/http";
 
-import "./errors.tsp";
+import "./error.tsp";
 import "./success.tsp";
 
-namespace Responses;
+namespace Core.Responses;

package/lib/{responses → core/responses}/success.tsp

@@ -1,4 +1,6 @@
-namespace Responses.Success;
+import "@typespec/http";
+
+namespace Core.Responses;
 
 model Success {
   @example(200)

package/lib/core/routes/index.tsp

@@ -0,0 +1,23 @@
+import "@typespec/http";
+import "@typespec/rest";
+
+// Import individual route files to provide a consistent interface
+import "./opportunities.tsp";
+
+/** A series of interfaces for CommonGrants API routes
+ *
+ * @example How to use the `Routes` namespace
+ *
+ * ```tsp
+ * import "@common-grants/core";
+ *
+ * using CommonGrants;
+ *
+ * namespace MyRoutes {
+ *   alias OpportunityRouter = Routes.Opportunities;
+ *
+ *   op List is OpportunityRouter.list;
+ * }
+ * ```
+ */
+namespace Core.Routes;

package/lib/{routes → core/routes}/opportunities.tsp

@@ -1,26 +1,14 @@
 import "../models/index.tsp";
 import "../responses/index.tsp";
+import "./utils.tsp";
 
 // Define the top-level namespace for CommonGrants routes
-namespace CommonGrants.Routes;
+namespace Core.Routes;
 
 // Expose the contents of the Http and Rest namespaces
 // these include the decorators @route, @get, etc.
 using TypeSpec.Http;
-using TypeSpec.Rest;
-using Responses;
-
-model PaginatedQuery {
-  /** The page to return */
-  @query
-  @pageIndex
-  page?: int32 = 1;
-
-  /** The number of items to return per page */
-  @query
-  @pageSize
-  perPage?: int32 = 100;
-}
+using Core;
 
 /** A re-usable interface for an Opportunities router
  *
@@ -37,14 +25,13 @@ model PaginatedQuery {
  * ```typespec
  * using TypeSpec.Http;
  *
- * @tag("Search")
+ * @tag("Opportunities")
  * @route("/opportunities/")
  * namespace Opportunities {
- * alias Router = Routes.Opportunities
- *
- * op list is Router.list;
- * op read is Router.read<CustomOpportunity>;
+ *   alias Router = Routes.Opportunities
  *
+ *   op list is Router.list;
+ *   op read is Router.read<CustomOpportunity>;
  * }
  * ```
  */
@@ -52,24 +39,25 @@ interface Opportunities {
   /** `GET /opportunities/` Get a paginated list of opportunities
    *
    * @template T Type of the paginated response model.
-   * Must be an extension of Models.OpportunityBase. Default is Models.OpportunityBase.
+   * 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>(
-    ...PaginatedQuery,
-  ): Success.Paginated<T> | Error.Unauthorized;
+    ...Utils.PaginatedQuery,
+  ): Responses.Paginated<T> | Responses.Unauthorized;
 
   /** `GET /opportunities/<id>` View opportunity details
    *
    * @template T Type of the response model.
-   * Must be an extension of Models.OpportunityBase. Default is Models.OpportunityBase.
+   * 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>(
-    @path id: Models.uuid,
-  ): Success.Ok<T> | Error.NotFound | Error.Unauthorized;
+    /** The ID of the opportunity to view */
+    @path id: Types.uuid,
+  ): Responses.Ok<T> | Responses.NotFound | Responses.Unauthorized;
 }

package/lib/core/routes/utils.tsp

@@ -0,0 +1,19 @@
+import "@typespec/http";
+
+using TypeSpec.Http;
+
+/** Utility models and functions for API routes */
+namespace Core.Routes.Utils;
+
+/** A set of query parameters for paginated routes */
+model PaginatedQuery {
+  /** The page to return */
+  @query
+  @pageIndex
+  page?: int32 = 1;
+
+  /** The number of items to return per page */
+  @query
+  @pageSize
+  pageSize?: int32 = 100;
+}

package/lib/{models/base.tsp → core/types.tsp}

@@ -1,4 +1,4 @@
-namespace CommonGrants.Models;
+namespace Core.Types;
 
 /** A time on a clock, without a timezone, in ISO 8601 format HH:mm:ss */
 @example(isoTime.fromISO("17:00:00"))

package/lib/main.tsp

@@ -3,27 +3,92 @@
 // 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";
+// Import items from the Core namespace to make them available outside the package
+import "./core/index.tsp";
+import "./api.tsp";
 
-using TypeSpec.Http;
+namespace CommonGrants;
 
-/** The base OpenAPI specification for a CommonGrants API
+/** Base data types, e.g. `uuid` and `isoDate`, used to build more complex fields and models
  *
- * In order for an API to be "compliant" with the CommonGrants protocol,
- * it must implement all of the routes included in this base specification.
+ * @example How to use the `Types` namespace
+ *
+ * ```tsp
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Types namespace
+ *
+ * model MyModel {
+ *   id: Types.uuid;
+ *   createdAt: Types.isoDate;
+ * }
+ * ```
+ */
+alias Types = Core.Types;
+
+/** A standard set of fields, e.g. `money` that can be reused across models
+ *
+ * @example How to use the `Fields` namespace
+ *
+ * ```tsp
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Fields namespace
+ *
+ * model MyModel {
+ *   amount: Fields.money;
+ * }
+ * ```
+ */
+alias Fields = Core.Fields;
+
+/** A standardized set of response schemas for CommonGrants API routes
+ *
+ * @example How to use the `Responses` namespace
+ *
+ * ```tsp
+ * import "@typespec/http";
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Responses namespace
+ * using TypeSpec.Http;
+ *
+ * @route("/pets")
+ * namespace Pets {
+ *   @get
+ *   getPets(): Responses.Ok<Pet> | Responses.Unauthorized;
+ * }
+ * ```
  */
-@service({
-  title: "Base API",
-})
-namespace CommonGrants.API;
+alias Responses = Core.Responses;
 
-@tag("Opportunities")
-@route("/opportunities")
-namespace Opportunities {
-  alias Router = Routes.Opportunities;
+/** A collection of models for the CommonGrants API
+ *
+ * @example How to use the `Models` namespace
+ *
+ * ```tsp
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Models namespace
+ *
+ * model MyModel extends Models.OpportunityBase {}
+ * ```
+ */
+alias Models = Core.Models;
 
-  op List is Router.list;
-  op Read is Router.read;
-}
+/** A series of routing interfaces for CommonGrants API endpoints
+ *
+ * @example How to use the `Routes` namespace
+ *
+ * ```tsp
+ * import "@common-grants/core";
+ *
+ * using CommonGrants; // exposes the Routes namespace
+ *
+ * namespace MyRoutes {
+ *   alias OpportunityRouter = Routes.Opportunities;
+ *
+ *   op List is OpportunityRouter.list;
+ * }
+ */
+alias Routes = Core.Routes;

package/package.json

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

package/lib/models/custom-enum.tsp

@@ -1,27 +0,0 @@
-namespace CommonGrants.Models;
-
-/**
- * A custom enum value, designed to be used as part of a union with known options
- *
- * @example How to use this CustomEnumValue in a union
- *
- * ```typespec
- * union OpportunityStatus {
- *   open: {
- *       value: "open",
- *       description?: "Opportunity is actively accepting applications",
- *   },
- *   closed: {
- *       value: "closed",
- *       description?: "Opportunity is no longer accepting applications",
- *   },
- *   custom: CustomEnumValue,
- * }
- * ```
- */
-@doc("Custom value not included in the standard list of options.")
-model CustomEnumValue {
-  value: "custom";
-  customValue: string;
-  description: string;
-}

package/lib/models/opportunity/status.tsp

@@ -1,33 +0,0 @@
-import "@typespec/json-schema";
-import "@typespec/openapi3";
-
-import "../custom-enum.tsp";
-
-namespace CommonGrants.Models.Opportunity;
-
-/** Union of values accepted for opportunity status */
-@JsonSchema.oneOf
-@OpenAPI.oneOf
-@discriminator("value")
-union OppStatus {
-  /** Opportunity is anticipated, but not yet accepting applications */
-  forecasted: {
-    value: "forecasted",
-    description?: "Opportunity is anticipated, but not yet accepting applications",
-  },
-
-  /** Opportunity is actively accepting applications */
-  open: {
-    value: "open",
-    description?: "Opportunity is actively accepting applications",
-  },
-
-  /** Opportunity is no longer accepting applications */
-  closed: {
-    value: "closed",
-    description?: "Opportunity is no longer accepting applications",
-  },
-
-  /** Custom opportunity status */
-  custom: CustomEnumValue,
-}

package/lib/routes/index.tsp

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