@pocketprep/types 1.16.26 → 1.18.1

package/API/BaseResource.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Common base for every API response resource.
+ *
+ * Responses are Parse-free and use ISO-8601 timestamp strings. Pointer
+ * fields hold raw id strings (or string arrays); the Nest repository layer
+ * translates Mongo storage shape into this contract at the boundary.
+ */
+export interface BaseResource {
+    id: string
+    createdAt: string
+    updatedAt: string
+}

package/API/Bundle.d.ts

@@ -0,0 +1,82 @@
+import { BaseResource } from './BaseResource'
+
+export interface MockExam extends BaseResource {
+    name: string
+    description?: string
+    enabled: boolean
+    durationSeconds: number
+    questionSerials: string[]
+}
+
+export interface ExamMetadata extends BaseResource {
+    hideReferences: boolean
+    examGuid: string
+    archivedCount: number
+    freeCount?: number
+    totalCount?: number
+    nativeAppName: string
+    releaseInfo?: {
+        name: string
+        description: string
+        message: string
+    }
+    descriptiveName: string
+    version: string
+    compositeKey: string
+    description?: string
+    isFree: boolean
+    /** Ids of the MockExams associated with this exam. */
+    mockExams: string[]
+    sunsetAt?: string
+    minorVersionMessaging?: {
+        type: 'newQuestions' | 'newMockExams'
+        count: number
+    }
+    appId?: string
+    knowledgeAreas?: {
+        [key: string]: {
+            name: string
+            count: number
+            specialCount: number
+        }
+    }
+    itemCount?: number
+    classicQuestions?: number
+    specialQuestions?: number
+}
+
+export interface Bundle extends BaseResource {
+    name: string
+    /** Ids of the ExamMetadata records in this bundle. */
+    exams: string[]
+    ios?: {
+        currentVersion: string
+        minVersion: string
+        appStoreId: string
+        appStoreURI: string
+        appStoreIds: string[]
+    }
+    android?: {
+        currentVersion: string
+        minVersion: string
+        appStoreId: string
+        appStoreURI: string
+        appStoreIds: string[]
+    }
+    isDisabled: boolean
+    seatPricingModel?: {
+        costPerSeat: number
+        customExamPrices?: { [examGuid: string]: number }
+    }
+}
+
+export interface FetchBundlesParams {
+    platform?: 'iOS' | 'Android'
+    appStoreId?: string
+}
+
+export interface FetchBundlesResponse {
+    bundles: Bundle[]
+    exams: ExamMetadata[]
+    mockExams: MockExam[]
+}

package/API/KeywordDefinition.d.ts

@@ -0,0 +1,18 @@
+import { BaseResource } from './BaseResource'
+
+export interface KeywordDefinition extends BaseResource {
+    keyword: string
+    definition: string
+    serial: string
+    /** ExamMetadata id (pointer flattened). */
+    examMetadata?: string
+}
+
+export interface SearchKeywordDefinitionsParams {
+    examMetadataId: string
+    serials: string[]
+}
+
+export interface SearchKeywordDefinitionsResponse {
+    keywords: KeywordDefinition[]
+}

package/API/LevelUp.d.ts

@@ -0,0 +1,7 @@
+export interface CheckLevelUpEligibilityParams {
+    examGuid: string
+}
+
+export interface CheckLevelUpEligibilityResponse {
+    eligible: boolean
+}

package/API/Question.d.ts

@@ -0,0 +1,74 @@
+import { BloomTaxonomyLevel, Subtopic } from '../Study/Class'
+import { IMatrixLabels, TPassageLabel } from '../CMS/Class'
+
+import { BaseResource } from './BaseResource'
+
+/** Shape of an individual choice on a Question. Matches Parse's stored shape. */
+export interface QuestionChoice {
+    text?: string
+    isCorrect: boolean
+    id: string
+    labelIndex?: number
+}
+
+/** Image-with-alt structure used by passage and explanation. */
+export interface QuestionImage {
+    url: string
+    altText: string
+    longAltText?: string
+}
+
+export interface Question extends BaseResource {
+    prompt: string
+    /** Subject id (pointer flattened). */
+    subject: string
+    subtopicId?: string
+    bloomTaxonomyLevel?: BloomTaxonomyLevel
+    choices: QuestionChoice[]
+    passage?: string
+    passageImage?: QuestionImage
+    explanation?: string
+    explanationImage?: QuestionImage
+    references?: string[]
+    serial: string
+    /** ExamMetadata id (pointer flattened). */
+    examMetadata: string
+    compositeKey: string
+    type:
+        | 'Multiple Choice'
+        | 'Multiple Correct Response'
+        | 'True/False'
+        | 'Matrix Checkbox'
+        | 'Matrix Radio Button'
+        | 'Multi-Part Multiple Choice'
+        | 'Build List'
+    addedDate: string
+    isArchived: boolean
+    isFree: boolean
+    isMockQuestion: boolean
+    /** QuestionScenario id (pointer flattened, optional). */
+    questionScenario?: string
+    matrixLabels?: IMatrixLabels
+    matrixChoiceLayout?: string[][]
+    passageLabel?: TPassageLabel
+    mpmcLabels?: string[]
+}
+
+export interface Subject extends BaseResource {
+    name: string
+    isArchived: boolean
+    /** ExamMetadata id (pointer flattened). */
+    examMetadata: string
+    questionCount?: number
+    subtopics?: Subtopic[]
+}
+
+export interface FetchQotdParams {
+    daysSinceEpoch: number
+    count?: number
+}
+
+export interface FetchQotdResponse {
+    questions: Question[]
+    subjects: Subject[]
+}

package/API/Session.d.ts

@@ -0,0 +1,9 @@
+import { BaseResource } from './BaseResource'
+
+export interface Session extends BaseResource {
+    sessionToken: string
+    expiresAt: string
+    /** User id (pointer flattened). */
+    user: string
+    createdWith?: { action: string; authProvider: string }
+}

package/API/User.d.ts

@@ -0,0 +1,30 @@
+import { BaseResource } from './BaseResource'
+
+export interface QuizSettings {
+    showCheckAnswerButton?: boolean
+    showAnswersAtEnd?: boolean
+    enableKeyboardShortcuts?: boolean
+}
+
+/**
+ * User response shape. Sensitive columns (`password`, `_hashed_password`,
+ * `stripeCustomerId`) are stripped at the flatten boundary so they never
+ * reach this contract.
+ */
+export interface User extends BaseResource {
+    email: string
+    firstName?: string
+    lastName?: string
+    username?: string
+    company?: string
+    currentApp?: string
+    currentExamGuid?: string
+    /** UserExamMetadata id (pointer flattened — UEM itself is no longer hydrated). */
+    currentUserExamMetadata?: string
+    lastActiveAt?: string
+    onboardingCompleted?: boolean
+    quizSettings?: QuizSettings
+    title?: string
+    version?: string
+    webConfig?: Record<string, unknown>
+}

package/API/index.d.ts

@@ -0,0 +1,7 @@
+export * from './BaseResource'
+export * from './Bundle'
+export * from './Question'
+export * from './KeywordDefinition'
+export * from './Session'
+export * from './User'
+export * from './LevelUp'

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/index.d.ts

@@ -4,6 +4,7 @@ import * as CMS from './CMS'
 import * as Teach from './Teach'
 import * as Support from './Support'
 import * as AI from './AI'
+import * as API from './API'
 
 export {
     Study,
@@ -11,6 +12,7 @@ export {
     Teach,
     Support,
     AI,
+    API,
 }
 
 export type Payload<T extends Parse.Object> = T extends Parse.Object<infer R>

package/package.json

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