Version: Next

Reference

Full reference for all constants, types, hooks, and API endpoints in src/lib/api/domains/foundation/self-service-registration.

Constants

Session modes

type RegistrationSessionMode =
  | "teacher_self_registration"
  | "student_intake"
  | "student_verification";

Session statuses

type RegistrationSessionStatus =
  | "draft"
  | "open"
  | "paused"
  | "closed"
  | "archived";

Roster policies

type RegistrationRosterPolicy =
  | "preloaded_only"   // only pre-assigned codes allowed
  | "open_with_code"   // any code holder can submit
  | "mixed";           // some pre-assigned, rest open

Audience types

type RegistrationAudienceType = "teacher" | "student";

Access code statuses

type RegistrationAccessCodeStatus =
  | "unused"
  | "started"
  | "submitted"
  | "needs_correction"
  | "approved"
  | "rejected"
  | "revoked"
  | "expired";

Submission statuses

type RegistrationSubmissionStatus =
  | "draft"
  | "submitted"
  | "needs_correction"
  | "resubmitted"
  | "approved"
  | "rejected"
  | "imported"
  | "cancelled";

Public next steps

type PublicRegistrationNextStep =
  | "complete_form"
  | "read_only_status"
  | "corrections_required";

Code formats

type RegistrationCodeFormat =
  | "human_readable_4_digit"   // e.g. "A1B2"
  | "human_readable_6_digit";  // e.g. "A1B2C3"

Code delivery methods

type RegistrationCodeDeliveryMethod =
  | "print"
  | "email"
  | "email_and_print";

Import modes

type RegistrationImportMode =
  | "update_existing_or_create"
  | "update_existing_only"
  | "create_new_only";

Manual submission sources

type ManualRegistrationSource =
  | "teacher_mobile_paper_capture"
  | "admin_paper_capture";

Core type shapes

RegistrationSession
RegistrationSubmission
RegistrationAccessCode
PublicRegistrationMe

type RegistrationSession = {
  id: string;
  tenantId: string;
  schoolId: string;
  mode: RegistrationSessionMode;
  title: string;
  description?: string | null;
  classDivisionId?: string | null;
  gradeLevelId?: string | null;
  academicYearId?: string | null;
  termId?: string | null;
  status: RegistrationSessionStatus;
  startsAt?: string | null;
  endsAt?: string | null;
  requiredFields: Record<string, unknown>;
  approvalPolicy: Record<string, unknown>;
  rosterPolicy: RegistrationRosterPolicy;
  expectedCount: number;
  createdBy?: string | null;
  updatedBy?: string | null;
  createdAt: string;
  updatedAt: string;
  progress?: RegistrationProgressSummary;
};

type RegistrationSubmission = {
  id: string;
  tenantId: string;
  schoolId: string;
  sessionId: string;
  gradeLevelId?: string | null;
  classDivisionId?: string | null;
  accessCodeId: string;
  personType: RegistrationAudienceType;
  status: RegistrationSubmissionStatus;
  existingUserId?: string | null;
  existingTeacherId?: string | null;
  existingStudentId?: string | null;
  officialTeacherId?: string | null;
  officialStudentId?: string | null;
  payload: Record<string, unknown>;
  normalizedIdentity: RegistrationSubmissionNormalizedIdentity;
  validationSummary: RegistrationSubmissionValidationSummary;
  sourceDocument: Record<string, unknown>;
  version: number;
  submittedAt?: string | null;
  reviewedAt?: string | null;
  importedAt?: string | null;
  reviewedBy?: string | null;
  importedBy?: string | null;
  reviewNotes?: string | null;
  rejectionReason?: string | null;
  correctionMessage?: string | null;
  session?: RegistrationSession;
  code?: RegistrationAccessCode;
  gradeLevel?: RegistrationSubmissionGradeLevel;
  classDivision?: RegistrationSubmissionClassDivision;
  teacherDetails?: RegistrationSubmissionTeacherDetails;
  createdAt: string;
  updatedAt: string;
};

type RegistrationAccessCode = {
  id: string;
  tenantId: string;
  schoolId: string;
  sessionId: string;
  codePlain?: string | null;   // only in generate/export responses
  codeLast4: string;
  prefix?: string | null;
  audienceType: RegistrationAudienceType;
  assignedStudentId?: string | null;
  assignedTeacherId?: string | null;
  assignedUserId?: string | null;
  rosterSnapshot: Record<string, unknown>;
  status: RegistrationAccessCodeStatus;
  attemptCount: number;
  expiresAt?: string | null;
  startedAt?: string | null;
  submittedAt?: string | null;
  approvedAt?: string | null;
  createdAt: string;
  updatedAt: string;
};

type PublicRegistrationMe = {
  session: PublicRegistrationSession;
  participant: RegistrationParticipant;
  selectionContext?: PublicRegistrationSelectionContext;
  submission: {
    id: string;
    status: RegistrationSubmissionStatus;
    version: number;
    canEdit: boolean;
    correctionMessage?: string | null;
    submittedAt?: string | null;
    payload?: Record<string, unknown>;
    validationSummary?: Record<string, unknown>;
  };
};

React Query hooks

Public (participant-facing)

Hook	Purpose
`useValidateRegistrationAccessCode(options?)`	Validate an access code and obtain a registration token
`usePublicRegistrationMe(token, options?)`	Load current session + submission state for a token
`useSavePublicRegistrationDraft(token, options?)`	Auto-save draft payload
`useSummarizePublicRegistrationDraft(token, options?)`	Pre-submit validation and summary text
`useSubmitPublicRegistration(token, options?)`	Final submission
`useResubmitPublicRegistrationCorrections(token, options?)`	Resubmit after staff requested corrections

Staff - sessions

Hook	Purpose
`useRegistrationSessions(params?, options?)`	List sessions with optional filters
`useRegistrationSession(id, options?)`	Get a single session
`useCreateRegistrationSession(options?)`	Create a new session
`useUpdateRegistrationSession(options?)`	Update session metadata
`useOpenRegistrationSession(options?)`	Transition session to `open`
`usePauseRegistrationSession(options?)`	Transition session to `paused`
`useCloseRegistrationSession(options?)`	Transition session to `closed`
`useArchiveRegistrationSession(options?)`	Transition session to `archived`
`useRegistrationSessionProgress(id, options?)`	Live progress counters for one session

Staff - access codes

Hook	Purpose
`useRegistrationAccessCodes(params?, options?)`	List access codes
`useGenerateRegistrationCodes(options?)`	Generate new codes for a session
`useExportRegistrationCodes(options?)`	Export/reprint an existing batch
`useRevokeRegistrationAccessCode(options?)`	Revoke a single code

Staff - submissions

Hook	Purpose
`useRegistrationSubmissions(params?, options?)`	List submissions
`useRegistrationSubmission(id, options?)`	Get one submission
`useReviewRegistrationSubmissionFields(options?)`	Annotate individual fields
`useRequestRegistrationCorrection(options?)`	Send correction request to participant
`useRejectRegistrationSubmission(options?)`	Permanently reject
`useApproveRegistrationSubmission(options?)`	Approve and trigger import
`useBulkApproveRegistrationSubmissions(options?)`	Approve multiple submissions at once
`useCreateManualRegistrationSubmission(options?)`	Paper/admin capture

Staff - dashboards

Hook	Purpose
`useSchoolRegistrationProgress(params?, options?)`	School-level rollup
`useClassTeacherRegistrationDashboard(options?)`	Class teacher focused view
`useMinistryRegistrationProgress(params?, options?)`	Tenant-wide oversight

Query key factories

All query keys are defined in keys.ts and should be used for cache invalidation:

import {
  publicRegistrationKeys,
  registrationSessionKeys,
  registrationAccessCodeKeys,
  registrationSubmissionKeys,
  registrationDashboardKeys,
} from "@/lib/api/domains/foundation/self-service-registration";

// Examples
publicRegistrationKeys.me(token)          // -> [..., "me", tokenCacheKey]
registrationSessionKeys.detail(tenant, id)
registrationSessionKeys.progress(tenant, id)
registrationSessionKeys.codes(tenant, id, params)
registrationSubmissionKeys.list(tenant, params)

API endpoint summary

All staff endpoints are prefixed with /api/v1/registrations/.
All public endpoints are prefixed with /api/v1/public/registrations/.

Sessions

Method	Path	Description
`GET`	`/registrations/sessions`	List sessions
`POST`	`/registrations/sessions`	Create session
`GET`	`/registrations/sessions/{id}`	Get session
`PATCH`	`/registrations/sessions/{id}`	Update session
`POST`	`/registrations/sessions/{id}/open`	Open
`POST`	`/registrations/sessions/{id}/pause`	Pause
`POST`	`/registrations/sessions/{id}/close`	Close
`POST`	`/registrations/sessions/{id}/archive`	Archive
`GET`	`/registrations/sessions/{id}/progress`	Progress summary
`POST`	`/registrations/sessions/{id}/codes/generate`	Generate codes
`POST`	`/registrations/sessions/{id}/codes/export`	Export/reprint batch
`POST`	`/registrations/sessions/{id}/submissions/bulk-approve`	Bulk approve
`POST`	`/registrations/sessions/{id}/manual-submissions`	Manual capture

Access codes

Method	Path	Description
`GET`	`/registrations/access-codes`	List codes
`POST`	`/registrations/codes/{id}/revoke`	Revoke code

Submissions

Method	Path	Description
`GET`	`/registrations/submissions`	List submissions
`GET`	`/registrations/submissions/{id}`	Get submission
`PATCH`	`/registrations/submissions/{id}/review-fields`	Flag fields
`POST`	`/registrations/submissions/{id}/request-correction`	Request correction
`POST`	`/registrations/submissions/{id}/reject`	Reject
`POST`	`/registrations/submissions/{id}/approve`	Approve + import

Dashboards

Method	Path	Description
`GET`	`/registrations/dashboards/school-progress`	School rollup
`GET`	`/registrations/dashboards/class-teacher`	Class teacher view
`GET`	`/registrations/dashboards/ministry-progress`	Ministry overview

Public (no auth required, token-based)

Method	Path	Description
`POST`	`/public/registrations/access-codes/validate`	Validate code + get token
`GET`	`/public/registrations/me`	Load form state
`PUT`	`/public/registrations/me/draft`	Save draft
`POST`	`/public/registrations/me/summary`	Pre-submit validation
`POST`	`/public/registrations/me/submit`	Final submit
`POST`	`/public/registrations/me/corrections`	Resubmit corrections

Source files

File	Purpose
`constants.ts`	All enum constants and their TypeScript union types
`types.ts`	All request/response type contracts
`client.ts`	`selfServiceRegistrationApi` (staff) and `publicSelfServiceRegistrationApi` (public)
`hooks.ts`	All TanStack Query hooks
`keys.ts`	Query key factories for cache management
`index.ts`	Barrel export

Constants​

Session modes​

Session statuses​

Roster policies​

Audience types​

Access code statuses​

Submission statuses​

Public next steps​

Code formats​

Code delivery methods​

Import modes​

Manual submission sources​

Core type shapes​

React Query hooks​

Public (participant-facing)​

Staff - sessions​

Staff - access codes​

Staff - submissions​

Staff - dashboards​

Query key factories​

API endpoint summary​

Sessions​

Access codes​

Submissions​

Dashboards​

Public (no auth required, token-based)​

Source files​