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

package/README.md

@@ -1,3 +1,12 @@
-# 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 contracts and business rules for the SP Connect API, published from
+the backend repository so that clients and the service cannot drift apart. Every payload is
+a zod schema with its type inferred from it, so `zod` is a peer dependency.
+
+```ts
+import { SubmitQuestionRequestSchema, QUESTION_TEXT_MAX_LENGTH } 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/contracts/config/routes.d.ts

@@ -0,0 +1,4 @@
+/** Stable public route constants. */
+export declare const API_PREFIX = "api";
+export declare const API_VERSION = "1";
+//# sourceMappingURL=routes.d.ts.map

package/contracts/config/routes.js

@@ -0,0 +1,4 @@
+/** Stable public route constants. */
+export const API_PREFIX = 'api';
+export const API_VERSION = '1';
+//# sourceMappingURL=routes.js.map

package/contracts/errors.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/** 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 declare const ErrorResponseSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, z.core.$strip>;
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+//# sourceMappingURL=errors.d.ts.map

package/contracts/errors.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/** 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',
+};
+/**
+ * `{ 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 const ErrorResponseSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    details: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+});
+//# sourceMappingURL=errors.js.map

package/contracts/index.d.ts

@@ -0,0 +1,11 @@
+export { API_PREFIX, API_VERSION } from './config/routes.js';
+export { ErrorCode, ErrorResponseSchema } from './errors.js';
+export type { ErrorResponse } from './errors.js';
+export { ROLES, RoleSchema } from './roles.js';
+export type { Role } from './roles.js';
+export { CognitoPoolResponseSchema } from '../modules/auth/contracts/cognito-pool.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 { SubmitQuestionRequestSchema, SubmitQuestionResponseSchema, } from '../modules/questions/contracts/submit-question.js';
+export type { SubmitQuestionRequest, SubmitQuestionResponse, } from '../modules/questions/contracts/submit-question.js';
+//# sourceMappingURL=index.d.ts.map

package/contracts/index.js

@@ -0,0 +1,7 @@
+export { API_PREFIX, API_VERSION } from './config/routes.js';
+export { ErrorCode, ErrorResponseSchema } from './errors.js';
+export { ROLES, RoleSchema } from './roles.js';
+export { CognitoPoolResponseSchema } 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 { SubmitQuestionRequestSchema, SubmitQuestionResponseSchema, } from '../modules/questions/contracts/submit-question.js';
+//# sourceMappingURL=index.js.map

package/contracts/roles.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const ROLES: readonly ["student", "expert", "admin"];
+export declare const RoleSchema: z.ZodEnum<{
+    student: "student";
+    expert: "expert";
+    admin: "admin";
+}>;
+export type Role = z.infer<typeof RoleSchema>;
+//# sourceMappingURL=roles.d.ts.map

package/contracts/roles.js

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export const ROLES = ['student', 'expert', 'admin'];
+export const RoleSchema = z.enum(ROLES);
+//# sourceMappingURL=roles.js.map

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

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const CognitoPoolResponseSchema: z.ZodObject<{
+    userPoolId: z.ZodString;
+    userPoolClientId: z.ZodString;
+}, z.core.$strip>;
+export type CognitoPoolResponse = z.infer<typeof CognitoPoolResponseSchema>;
+//# sourceMappingURL=cognito-pool.d.ts.map

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

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export const CognitoPoolResponseSchema = z.object({
+    userPoolId: z.string().min(1),
+    userPoolClientId: z.string().min(1),
+});
+//# sourceMappingURL=cognito-pool.js.map

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

@@ -0,0 +1,3 @@
+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';
+//# sourceMappingURL=question-rules.d.ts.map

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

@@ -0,0 +1,3 @@
+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';
+//# sourceMappingURL=question-rules.js.map

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

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+/** Public request and response shapes owned and published by the questions module. */
+export declare const SubmitQuestionRequestSchema: z.ZodObject<{
+    programmeId: z.ZodString;
+    questionText: z.ZodString;
+}, z.core.$strip>;
+export type SubmitQuestionRequest = z.infer<typeof SubmitQuestionRequestSchema>;
+export declare const SubmitQuestionResponseSchema: z.ZodObject<{
+    questionId: z.ZodUUID;
+}, z.core.$strip>;
+export type SubmitQuestionResponse = z.infer<typeof SubmitQuestionResponseSchema>;
+//# sourceMappingURL=submit-question.d.ts.map

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

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { EXTERNAL_ID_MAX_LENGTH, EXTERNAL_ID_PATTERN, QUESTION_TEXT_MAX_LENGTH, QUESTION_TEXT_MIN_LENGTH, } from './question-rules.js';
+/** Public request and response shapes owned and published by the questions module. */
+export const SubmitQuestionRequestSchema = z.object({
+    programmeId: z.string().trim().min(1).max(EXTERNAL_ID_MAX_LENGTH).regex(EXTERNAL_ID_PATTERN),
+    questionText: z.string().trim().min(QUESTION_TEXT_MIN_LENGTH).max(QUESTION_TEXT_MAX_LENGTH),
+});
+export const SubmitQuestionResponseSchema = z.object({
+    questionId: z.uuid(),
+});
+//# sourceMappingURL=submit-question.js.map

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

@@ -0,0 +1,5 @@
+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;
+//# sourceMappingURL=question-constraints.d.ts.map

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

@@ -0,0 +1,5 @@
+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;
+//# sourceMappingURL=question-constraints.js.map

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

@@ -0,0 +1,9 @@
+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];
+//# sourceMappingURL=question-error-codes.d.ts.map

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

@@ -0,0 +1,8 @@
+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',
+};
+//# sourceMappingURL=question-error-codes.js.map

package/package.json

@@ -1,6 +1,29 @@
 {
   "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.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./contracts/index.d.ts",
+      "import": "./contracts/index.js"
+    }
+  },
+  "files": [
+    "contracts/**/*.js",
+    "contracts/**/*.d.ts",
+    "modules/**/*.js",
+    "modules/**/*.d.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "description": "Public API contracts and business rules of the SP Connect backend.",
+  "license": "UNLICENSED"
+}