@studyportals/sp-connect-backend-contracts 0.0.0-stage → 1.0.0-beta.1

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @studyportals/sp-connect-backend-contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Request and response types, error codes and business rules for the SP Connect API, published
+from the backend repository so that clients and the service cannot drift apart. The package has
+no runtime dependencies: it contains TypeScript types and constants only.
+
+```ts
+import {
+  QUESTION_TEXT_MAX_LENGTH,
+  QuestionErrorCode,
+} from '@studyportals/sp-connect-backend-contracts';
+import type { SubmitQuestionRequest } from '@studyportals/sp-connect-backend-contracts';
+```
+
+This package contains no client: it describes the payloads, not how to send them.

package/dist/contracts/config/routes.d.ts

@@ -0,0 +1,3 @@
+/** Stable public route constants. */
+export declare const API_PREFIX = "api";
+export declare const API_VERSION = "1";

package/dist/contracts/config/routes.js

@@ -0,0 +1,3 @@
+/** Stable public route constants. */
+export const API_PREFIX = 'api';
+export const API_VERSION = '1';

package/dist/contracts/errors.d.ts

@@ -0,0 +1,15 @@
+/** Error codes the API returns that no module owns; module codes live in each module's contracts. */
+export declare const ErrorCode: {
+    readonly Internal: "internal_error";
+    readonly InvalidRequestBody: "request.invalid_body";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * `{ code, message, details? }` body of the API's own errors. Nest's built-in HTTP errors, such as
+ * a 401 from the auth guard, keep Nest's `{ statusCode, message, error }` body instead.
+ */
+export interface ErrorResponse {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: Record<string, string | number | boolean>;
+}

package/dist/contracts/errors.js

@@ -0,0 +1,5 @@
+/** Error codes the API returns that no module owns; module codes live in each module's contracts. */
+export const ErrorCode = {
+    Internal: 'internal_error',
+    InvalidRequestBody: 'request.invalid_body',
+};

package/dist/contracts/index.d.ts

@@ -0,0 +1,8 @@
+export { API_PREFIX, API_VERSION } from './config/routes.js';
+export { ErrorCode } from './errors.js';
+export type { ErrorResponse } from './errors.js';
+export { ROLES } from './roles.js';
+export type { Role } from './roles.js';
+export type { CognitoPoolResponse } from '../modules/auth/contracts/cognito-pool.js';
+export { EXTERNAL_ID_MAX_LENGTH, EXTERNAL_ID_PATTERN, QUESTION_TEXT_MAX_LENGTH, QUESTION_TEXT_MIN_LENGTH, QuestionErrorCode, } from '../modules/questions/contracts/question-rules.js';
+export type { SubmitQuestionRequest, SubmitQuestionResponse, } from '../modules/questions/contracts/submit-question.js';

package/dist/contracts/index.js

@@ -0,0 +1,4 @@
+export { API_PREFIX, API_VERSION } from './config/routes.js';
+export { ErrorCode } from './errors.js';
+export { ROLES } from './roles.js';
+export { EXTERNAL_ID_MAX_LENGTH, EXTERNAL_ID_PATTERN, QUESTION_TEXT_MAX_LENGTH, QUESTION_TEXT_MIN_LENGTH, QuestionErrorCode, } from '../modules/questions/contracts/question-rules.js';

package/dist/contracts/roles.d.ts

@@ -0,0 +1,2 @@
+export declare const ROLES: readonly ["student", "expert", "admin"];
+export type Role = (typeof ROLES)[number];

package/dist/contracts/roles.js

@@ -0,0 +1 @@
+export const ROLES = ['student', 'expert', 'admin'];

package/dist/modules/auth/contracts/cognito-pool.d.ts

@@ -0,0 +1,4 @@
+export interface CognitoPoolResponse {
+    readonly userPoolId: string;
+    readonly userPoolClientId: string;
+}

package/dist/modules/auth/contracts/cognito-pool.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/questions/contracts/question-rules.d.ts

@@ -0,0 +1,2 @@
+export { EXTERNAL_ID_MAX_LENGTH, EXTERNAL_ID_PATTERN, QUESTION_TEXT_MAX_LENGTH, QUESTION_TEXT_MIN_LENGTH, } from '../domain/question-constraints.js';
+export { QuestionErrorCode } from '../domain/question-error-codes.js';

package/dist/modules/questions/contracts/question-rules.js

@@ -0,0 +1,2 @@
+export { EXTERNAL_ID_MAX_LENGTH, EXTERNAL_ID_PATTERN, QUESTION_TEXT_MAX_LENGTH, QUESTION_TEXT_MIN_LENGTH, } from '../domain/question-constraints.js';
+export { QuestionErrorCode } from '../domain/question-error-codes.js';

package/dist/modules/questions/contracts/submit-question.d.ts

@@ -0,0 +1,11 @@
+/** Public request and response shapes owned and published by the questions module. */
+export interface SubmitQuestionRequest {
+    /** Up to `EXTERNAL_ID_MAX_LENGTH` characters matching `EXTERNAL_ID_PATTERN`. */
+    readonly programmeId: string;
+    /** `QUESTION_TEXT_MIN_LENGTH` to `QUESTION_TEXT_MAX_LENGTH` characters after trimming. */
+    readonly questionText: string;
+}
+export interface SubmitQuestionResponse {
+    /** A UUID. */
+    readonly questionId: string;
+}

package/dist/modules/questions/contracts/submit-question.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/questions/domain/question-constraints.d.ts

@@ -0,0 +1,4 @@
+export declare const EXTERNAL_ID_MAX_LENGTH = 128;
+export declare const EXTERNAL_ID_PATTERN: RegExp;
+export declare const QUESTION_TEXT_MIN_LENGTH = 10;
+export declare const QUESTION_TEXT_MAX_LENGTH = 280;

package/dist/modules/questions/domain/question-constraints.js

@@ -0,0 +1,4 @@
+export const EXTERNAL_ID_MAX_LENGTH = 128;
+export const EXTERNAL_ID_PATTERN = /^[A-Za-z0-9._:-]+$/;
+export const QUESTION_TEXT_MIN_LENGTH = 10;
+export const QUESTION_TEXT_MAX_LENGTH = 280;

package/dist/modules/questions/domain/question-error-codes.d.ts

@@ -0,0 +1,8 @@
+export declare const QuestionErrorCode: {
+    readonly InvalidId: "question.invalid_id";
+    readonly InvalidProgrammeId: "question.invalid_programme_id";
+    readonly InvalidStudentId: "question.invalid_student_id";
+    readonly InvalidText: "question.invalid_text";
+    readonly ProgrammeNotFound: "question.programme_not_found";
+};
+export type QuestionErrorCode = (typeof QuestionErrorCode)[keyof typeof QuestionErrorCode];

package/dist/modules/questions/domain/question-error-codes.js

@@ -0,0 +1,7 @@
+export const QuestionErrorCode = {
+    InvalidId: 'question.invalid_id',
+    InvalidProgrammeId: 'question.invalid_programme_id',
+    InvalidStudentId: 'question.invalid_student_id',
+    InvalidText: 'question.invalid_text',
+    ProgrammeNotFound: 'question.programme_not_found',
+};

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@studyportals/sp-connect-backend-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta.1",
+  "description": "Public API contracts and business rules of the SP Connect backend.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/contracts/index.d.ts",
+      "import": "./dist/contracts/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/*.tgz"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  }
+}