@pocketprep/types 1.16.26 → 1.17.0

package/Study/Api/Auth.d.ts

@@ -0,0 +1,56 @@
+import { UserJSON } from '../Class'
+
+/**
+ * REST API contracts for the Nest `AuthController`.
+ */
+
+/**
+ * POST /auth/register
+ *
+ * Create a new user account. Returns the persisted user with sensitive
+ * fields (password hashes, Stripe customer id) stripped.
+ */
+export type register = (params: {
+    email: string
+    password: string
+    name: string
+}) => UserJSON
+
+/**
+ * POST /auth/login
+ *
+ * Exchange credentials for a session token. Returns a deliberately trimmed
+ * user envelope — only the fields a client needs immediately after login.
+ * Full user data is available via /users/me using the returned session token.
+ */
+export type login = (params: {
+    email: string
+    password: string
+}) => {
+    sessionToken: string
+    user: {
+        id: string
+        email: string
+        firstName?: string
+        lastName?: string
+    }
+}
+
+/**
+ * GET /auth/profile
+ *
+ * Returns the authenticated user with sensitive fields stripped. Equivalent
+ * to GET /users/me but lives under /auth for legacy compatibility.
+ */
+export type getProfile = () => UserJSON
+
+/**
+ * POST /auth/logout
+ *
+ * Invalidates the session token supplied via the `x-parse-session-token`
+ * header. Always responds with a generic success message regardless of
+ * whether the token was already invalid.
+ */
+export type logout = () => {
+    message: string
+}

package/Study/Api/Bundles.d.ts

@@ -0,0 +1,20 @@
+import { BundleJSON } from '../Class'
+
+/**
+ * REST API contracts for the Nest `BundlesController`.
+ */
+
+/**
+ * GET /bundles
+ *
+ * Fetch active bundles. When both `platform` and `appStoreId` are supplied,
+ * results are filtered to bundles matching that App Store entry; otherwise
+ * all active bundles are returned. Supplying only one of the two is an
+ * error (HTTP 400).
+ */
+export type fetchBundles = (params: {
+    platform?: 'iOS' | 'Android'
+    appStoreId?: string
+}) => {
+    bundles: BundleJSON[]
+}

package/Study/Api/Exams.d.ts

@@ -0,0 +1,185 @@
+import {
+    ConceptQuizJSON,
+    ExamMetadataJSON,
+    GlobalQuestionMetricJSON,
+    LicenseJSON,
+    PrebuiltQuizJSON,
+    QuestionJSON,
+    QuizJSON,
+    SubscriptionJSON,
+    UserExamMetadataJSON,
+    UserJSON,
+} from '../Class'
+import { TLevelUpProgress } from '../Cloud'
+
+/**
+ * REST API contracts for the Nest `ExamsController`.
+ *
+ * Mirrors the `Study.Cloud` convention: each endpoint is exported as a
+ * callable type signature whose first argument is the request payload
+ * (path + query + body merged) and whose return type is the response body.
+ *
+ * Consume via:
+ *   type Params = Parameters<Study.Api.Exams.fetchQotd>[0]
+ *   type Response = ReturnType<Study.Api.Exams.fetchQotd>
+ */
+
+/**
+ * Subset of `Question` shape returned by the keyword search endpoint —
+ * intentionally trimmed for clients that only need a quick keyword glossary.
+ */
+export interface KeywordSummary {
+    serial: string
+    keyword: string
+    definition: string
+}
+
+/**
+ * GET /exams/:examMetadataId/qotd
+ *
+ * Returns one or more Question(s) of the Day for the given exam.
+ * The day is clamped to within ±1 of today server-side; clients
+ * cannot request arbitrary historical or future questions.
+ */
+export type fetchQotd = (params: {
+    examMetadataId: string
+    daysSinceEpoch: number
+    count?: number
+}) => QuestionJSON[]
+
+/**
+ * GET /exams/:examMetadataId/questions/quiz
+ *
+ * Build a quiz: select `questionCount` eligible questions for the user,
+ * filtered by subject and quiz-mode-style `include` flags. The
+ * `result` envelope mirrors the legacy Cloud function's response shape.
+ */
+export type fetchQuizQuestions = (params: {
+    examMetadataId: string
+    questionCount: number
+    quizMode?: number
+    subjectIds?: string[]
+    includeNew?: boolean
+    includeAnswered?: boolean
+    includeFlagged?: boolean
+    includeIncorrect?: boolean
+    includeMatrixQuestions?: boolean
+    includeBuildListQuestions?: boolean
+    includeMPMCQuestions?: boolean
+}) => {
+    result: QuestionJSON[]
+}
+
+/**
+ * GET /exams/:examMetadataId/question-metrics
+ *
+ * Returns global (cross-user, aggregate) metrics for the supplied question
+ * serials, or every question on the exam if `serials` is omitted.
+ * Duplicate metric rows per serial are collapsed by most-recent
+ * `_updated_at`.
+ */
+export type fetchGlobalQuestionMetrics = (params: {
+    examMetadataId: string
+    serials?: string[]
+}) => GlobalQuestionMetricJSON[]
+
+/**
+ * POST /exams/:examMetadataId/keyword-definitions/search
+ *
+ * Returns the keyword glossary entries for the supplied question serials.
+ * POST + `/search` suffix is used so the (potentially unbounded) `serials`
+ * array doesn't need to live in a query string.
+ */
+export type searchKeywordDefinitions = (params: {
+    examMetadataId: string
+    serials: string[]
+}) => {
+    keywords: KeywordSummary[]
+}
+
+/**
+ * POST /exams/:examMetadataId/questions/by-quiz-ids
+ *
+ * Returns the full set of questions that appeared in the given quizzes,
+ * scoped to the authenticated user. Used by clients to rehydrate quiz
+ * history without re-fetching the full question pool.
+ */
+export type fetchQuestionsByQuizIds = (params: {
+    examMetadataId: string
+    quizIds: string[]
+}) => QuestionJSON[]
+
+/**
+ * POST /exams/:examMetadataId/quiz
+ *
+ * Records a completed quiz and triggers downstream side effects:
+ * answer updates, global metrics, level-up progress, and (optionally)
+ * a recommended next quiz.
+ */
+export type recordQuiz = (params: {
+    examMetadataId: string
+    answers: {
+        isCorrect: boolean
+        selectedChoices: string[]
+        questionSerial: string
+    }[]
+    durationSeconds: number
+    mode: number
+    platform: string
+    startedAt: string
+    mockExamId?: string
+    levelSubjectId?: string
+    prebuiltQuizId?: string
+    conceptQuizId?: string
+    includeRecommendedNext?: boolean
+}) => {
+    quiz: QuizJSON
+    globalMetrics: GlobalQuestionMetricJSON[]
+    levelUpProgress?: TLevelUpProgress
+    feedback?: {
+        progressDescription?: string
+    }
+}
+
+/**
+ * GET /exams/:examMetadataId/user-data
+ *
+ * Bulk-fetch every piece of state the client needs for an exam in one
+ * round trip: user, exam metadata, quiz history, subscriptions, referral
+ * info, level-up data, optional question metrics, assignments, licenses,
+ * and concept quizzes. `lastFetchedAt` lets clients pull only deltas.
+ */
+export type fetchUserData = (params: {
+    examMetadataId: string
+    lastFetchedAt?: string
+    includeQuestionMetrics?: boolean
+}) => {
+    user: UserJSON
+    examMetadata: ExamMetadataJSON
+    userExamMetadata?: UserExamMetadataJSON
+    quizzes: QuizJSON[]
+    subscriptions: SubscriptionJSON[]
+    referralInfo?: {
+        redeemedUsersCount: number
+        code: string
+    }
+    subjectsWithLevels: {
+        subjectName: string
+        subjectId: string
+        levels: number[]
+    }[]
+    questionMetrics?: {
+        answeredCorrectlyCount: number
+        answeredIncorrectlyCount: number
+        questionSerial: string
+        choiceStats: Partial<Record<string, number>>
+        examGuid: string
+        objectId: string
+    }[]
+    assignments: PrebuiltQuizJSON[]
+    licenses: LicenseJSON[]
+    userFlags: {
+        assignmentsEnabled: boolean
+    }
+    conceptQuizzes?: ConceptQuizJSON[]
+}

package/Study/Api/LevelUp.d.ts

@@ -0,0 +1,15 @@
+/**
+ * REST API contracts for the Nest `LevelUpController`.
+ */
+
+/**
+ * GET /level-up/eligibility
+ *
+ * Returns whether the given exam (or its parent bundle) is enrolled in the
+ * LevelUp adaptive-difficulty program.
+ */
+export type checkLevelUpEligibility = (params: {
+    examGuid: string
+}) => {
+    eligible: boolean
+}

package/Study/Api/Users.d.ts

@@ -0,0 +1,37 @@
+import { UserJSON, UserExamMetadataJSON } from '../Class'
+
+/**
+ * REST API contracts for the Nest `UsersController`.
+ */
+
+/**
+ * GET /users/me
+ *
+ * Returns the authenticated user (with currentUserExamMetadata hydrated).
+ * Sensitive fields (password hashes, Stripe customer id) are stripped at
+ * the schema's `toJSON` boundary.
+ */
+export type getCurrentUser = () => UserJSON
+
+/**
+ * GET /users
+ *
+ * Returns every user in the system, sensitive fields stripped. Listing
+ * endpoint — should be admin-gated at the route level.
+ */
+export type findAll = () => UserJSON[]
+
+/**
+ * PUT /users/me/current-exam
+ *
+ * Sets the authenticated user's currently-selected exam. Finds or creates
+ * the corresponding `UserExamMetadata`. Short-circuits with
+ * `isSameExam: true` when the user is already on the requested exam.
+ */
+export type updateCurrentExam = (params: {
+    examMetadataId: string
+}) => {
+    isSameExam: boolean
+    isBrandNewExam: boolean
+    uem: UserExamMetadataJSON
+}

package/Study/Api/index.d.ts

@@ -0,0 +1,7 @@
+import * as Auth from './Auth'
+import * as Bundles from './Bundles'
+import * as Exams from './Exams'
+import * as LevelUp from './LevelUp'
+import * as Users from './Users'
+
+export { Auth, Bundles, Exams, LevelUp, Users }

package/Study/index.d.ts

@@ -1,4 +1,5 @@
+import * as Api from './Api'
 import * as Class from './Class'
 import * as Cloud from './Cloud'
 
-export { Class, Cloud }
+export { Api, Class, Cloud }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pocketprep/types",
-  "version": "1.16.26",
+  "version": "1.17.0",
   "description": "Pocket Prep type declarations",
   "repository": {
     "type": "git",