better-supabase 0.13.0 → 0.14.0

package/dist/blocks/courses/index.d.ts

@@ -0,0 +1,341 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "../../standard-DbQsD2xZ.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-3w4MZr8U.js";
+import { Ct as Events } from "../../events-DbLjvxDX.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { n as BlockOptions } from "../../block-helpers-BaugZlJV.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-d53POsem.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-CmjPKqQ_.js";
+import { n as coursesSqlOptions, t as CoursesSqlOptions } from "../../options-Dz3hJxUw.js";
+import { Gt as SectionWrite, Lt as Section, c as BlockOf, rn as EntitySchema } from "../../define-block-COpcS6aT.js";
+import { a as FormDefinition, l as FormJsonSchema } from "../../form-definition-BjEtH8BT.js";
+//#region src/blocks/courses/courses.d.ts
+declare const COURSE_STATUSES: readonly ["draft", "published", "archived"];
+declare const LESSON_KINDS: readonly ["content", "video", "quiz"];
+declare const LEARNER_STATUSES: readonly ["active", "completed", "cancelled"];
+/** Readers see published courses; managers see every status. */
+type CourseStatus = (typeof COURSE_STATUSES)[number];
+/** A quiz lesson is graded by a form of the `forms` block. */
+type CourseLessonKind = (typeof LESSON_KINDS)[number];
+/** Where a learner's enrollment in a course stands. */
+type CourseLearnerStatus = (typeof LEARNER_STATUSES)[number];
+/** A course. `F` types the extra columns the `fields` schema describes. */
+interface Course<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  /** Unique in the organization. */
+  readonly key: string;
+  readonly title: string;
+  readonly summary?: string;
+  readonly status: CourseStatus;
+  /** Whether completing the course issues a certificate. */
+  readonly certificate: boolean;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+/** A course to create (without `id`) or change (with it). */
+interface CourseInput<F extends object = Record<never, never>> {
+  readonly id?: string;
+  readonly key?: string;
+  readonly title?: string;
+  readonly summary?: string | null;
+  readonly status?: CourseStatus;
+  readonly certificate?: boolean;
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+/** A module of a course: a group of lessons. */
+interface CourseModule {
+  readonly id: string;
+  readonly courseId: string;
+  readonly title: string;
+  /** Its fractional rank key (ADR 0021): modules sort by it. */
+  readonly rank: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface CourseModuleInput {
+  readonly id?: string;
+  readonly title?: string;
+  /** A rank key; a new module without one goes last. */
+  readonly rank?: string;
+}
+/** A lesson with its content, as managers save it. */
+interface CourseLesson {
+  readonly id: string;
+  readonly courseId: string;
+  readonly moduleId: string;
+  readonly title: string;
+  readonly kind: CourseLessonKind;
+  /** The content, such as a rich-text document. */
+  readonly body?: unknown;
+  readonly mediaUrl?: string;
+  /** The form that grades a quiz lesson. */
+  readonly formId?: string;
+  /** Required lessons count toward completing the course. */
+  readonly required: boolean;
+  readonly minutes?: number;
+  readonly rank: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface CourseLessonInput {
+  readonly id?: string;
+  readonly moduleId?: string;
+  readonly title?: string;
+  readonly kind?: CourseLessonKind;
+  readonly body?: unknown;
+  readonly mediaUrl?: string | null;
+  readonly formId?: string | null;
+  readonly required?: boolean;
+  readonly minutes?: number | null;
+  /** A rank key; a lesson without one goes last in its module. */
+  readonly rank?: string;
+}
+/** A learner's state in one lesson. */
+interface LessonProgress {
+  readonly lessonId: string;
+  readonly startedAt: Temporal.Instant;
+  readonly completedAt?: Temporal.Instant;
+  /** Quiz submissions so far. */
+  readonly attempts: number;
+  readonly submissionId?: string;
+  readonly score?: number;
+  readonly maxScore?: number;
+  readonly passed?: boolean;
+}
+/** A certificate for a completed course. */
+interface CourseCertificate {
+  readonly id: string;
+  readonly courseId: string;
+  readonly userId: string;
+  /** The random value a verification link carries. */
+  readonly code: string;
+  readonly issuedAt: Temporal.Instant;
+  readonly revokedAt?: Temporal.Instant;
+}
+/** A learner's progress in a course. */
+interface CourseLearner {
+  readonly enrollmentId: string;
+  readonly courseId: string;
+  readonly organizationId: string;
+  readonly userId: string;
+  readonly status: CourseLearnerStatus;
+  /** Completed required lessons. */
+  readonly completedLessons: number;
+  /** Required lessons. */
+  readonly totalLessons: number;
+  readonly lessons: readonly LessonProgress[];
+  readonly certificate?: CourseCertificate;
+  readonly enrolledAt: Temporal.Instant;
+  readonly completedAt?: Temporal.Instant;
+  readonly cancelledAt?: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** A lesson in an outline: no content, with the caller's completion. */
+interface CourseOutlineLesson {
+  readonly id: string;
+  readonly moduleId: string;
+  readonly title: string;
+  readonly kind: CourseLessonKind;
+  readonly required: boolean;
+  readonly minutes?: number;
+  readonly rank: string;
+  readonly completedAt?: Temporal.Instant;
+}
+interface CourseOutlineModule {
+  readonly id: string;
+  readonly title: string;
+  readonly rank: string;
+  readonly lessons: readonly CourseOutlineLesson[];
+}
+/** A course with its modules and lessons in order, and the caller's progress. */
+interface CourseOutline<F extends object = Record<never, never>> extends Course<F> {
+  readonly modules: readonly CourseOutlineModule[];
+  /** Unset when the caller isn't enrolled. */
+  readonly progress?: CourseLearner;
+}
+/** A quiz lesson's form, without its answer key. */
+interface CourseQuiz {
+  readonly formId: string;
+  readonly title: string;
+  readonly status: string;
+  readonly versionId?: string;
+  /** The form definition the answers follow, without points or answers. */
+  readonly definition?: FormDefinition;
+  /** The JSON Schema the answers must match. */
+  readonly schema?: FormJsonSchema;
+}
+/** A lesson as the player shows it. */
+interface CourseLessonView extends CourseLesson {
+  readonly quiz?: CourseQuiz;
+  readonly progress?: LessonProgress;
+}
+/** What `submitQuiz` returns. */
+interface CourseQuizResult {
+  /** The forms submission, with its score. */
+  readonly submission: Readonly<Record<string, unknown>>;
+  /** Whether it completed the lesson. */
+  readonly passed: boolean;
+  readonly progress: CourseLearner;
+}
+/** What `verifyCertificate` returns for a known code. */
+interface CourseCertificateCheck {
+  readonly id: string;
+  readonly courseId: string;
+  readonly courseTitle: string;
+  readonly organizationId: string;
+  readonly issuedAt: Temporal.Instant;
+  readonly revokedAt?: Temporal.Instant;
+  readonly valid: boolean;
+}
+interface CourseLearnersFilter {
+  readonly status?: CourseLearnerStatus;
+  /** Default 50, at most 200. */
+  readonly pageSize?: number;
+  /** Learners changed before this instant, for the next page. */
+  readonly before?: Temporal.Instant;
+}
+interface Courses<F extends object = Record<never, never>> {
+  /** Creates or changes a course. */
+  save(course: CourseInput<F>): AsyncResult<Course<F>>;
+  /** The organization's courses by title; readers get the published ones. */
+  list(options?: {
+    readonly status?: CourseStatus;
+  }): AsyncResult<readonly Course<F>[]>;
+  /** Deletes a course with its enrollments; `false` when it was gone. */
+  delete(courseId: string): AsyncResult<boolean>;
+  /** The course with its modules and lessons in rank order. */
+  outline(courseId: string): AsyncResult<CourseOutline<F>>;
+  saveModule(courseId: string, module: CourseModuleInput): AsyncResult<CourseModule>;
+  /** Deletes a module with its lessons; `false` when it was gone. */
+  deleteModule(moduleId: string): AsyncResult<boolean>;
+  saveLesson(courseId: string, lesson: CourseLessonInput): AsyncResult<CourseLesson>;
+  deleteLesson(lessonId: string): AsyncResult<boolean>;
+  /** A lesson with its content and quiz, for managers and enrolled learners. */
+  lesson(lessonId: string): AsyncResult<CourseLessonView>;
+  /**
+   * Enrolls the caller, or `userId` with `courses.enroll`, in a published
+   * course. A cancelled enrollment starts again with its completed lessons.
+   */
+  enroll(courseId: string, userId?: string): AsyncResult<CourseLearner>;
+  /** Cancels an active enrollment; its progress stays. */
+  unenroll(courseId: string, userId?: string): AsyncResult<CourseLearner>;
+  /** Records that the caller opened a lesson. */
+  start(lessonId: string): AsyncResult<LessonProgress>;
+  /** Marks a content or video lesson done for the caller. */
+  complete(lessonId: string): AsyncResult<CourseLearner>;
+  /** Marks a lesson not done again. */
+  reset(lessonId: string): AsyncResult<CourseLearner>;
+  /**
+   * Submits answers to a quiz lesson. The database grades them; a passed
+   * submission completes the lesson.
+   */
+  submitQuiz(lessonId: string, answers: Readonly<Record<string, unknown>>): AsyncResult<CourseQuizResult>;
+  /** The caller's progress, or another user's; `null` when not enrolled. */
+  progress(courseId: string, userId?: string): AsyncResult<CourseLearner | null>;
+  /** The course's learners, most recently changed first. */
+  learners(courseId: string, filter?: CourseLearnersFilter): AsyncResult<readonly CourseLearner[]>;
+  /** Checks a certificate by its code; `null` for an unknown code. */
+  verifyCertificate(code: string): AsyncResult<CourseCertificateCheck | null>;
+  /** Revokes a certificate; `false` when it already was. */
+  revokeCertificate(certificateId: string): AsyncResult<boolean>;
+}
+interface CoursesOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the course's extra columns
+   * (`blocks.courses.options.extraColumns`), keyed by database name. It types
+   * and parses them on reads, and validates them on `save`.
+   */
+  readonly fields?: S;
+  readonly hooks?: NoInfer<BlockHooks<Courses<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/**
+ * The courses block: courses of modules and lessons, quizzes graded by forms,
+ * per-lesson progress, completion and certificates, on enrollments.
+ */
+export declare function createCourses<S extends StandardSchemaV1 | undefined = undefined>(options: CoursesOptions<S>): Courses<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/courses/events.d.ts
+/** `course.saved` and `course.deleted`. */
+interface CourseEventData {
+  readonly organizationId: string;
+  /** The course. */
+  readonly id: string;
+  readonly key: string;
+  readonly status: string;
+}
+/** `course.enrolled`, `course.unenrolled` and `course.completed`. */
+interface CourseLearnerEventData {
+  readonly organizationId: string;
+  /** The course. */
+  readonly id: string;
+  readonly userId: string;
+  readonly enrollmentId: string;
+}
+/** `course_lesson.completed`: a learner finished a lesson. */
+interface CourseLessonCompletedEventData {
+  readonly organizationId: string;
+  /** The lesson. */
+  readonly id: string;
+  readonly courseId: string;
+  readonly userId: string;
+  readonly enrollmentId: string;
+}
+/** `course_certificate.issued` and `course_certificate.revoked`. */
+interface CourseCertificateEventData {
+  readonly organizationId: string;
+  /** The certificate. */
+  readonly id: string;
+  readonly courseId: string;
+  readonly userId: string;
+  readonly enrollmentId: string;
+}
+/** The events of the `courses` block: type to data. */
+type CoursesEvents = {
+  readonly "course.saved": CourseEventData;
+  readonly "course.deleted": CourseEventData;
+  readonly "course.enrolled": CourseLearnerEventData;
+  readonly "course.unenrolled": CourseLearnerEventData;
+  readonly "course.completed": CourseLearnerEventData;
+  readonly "course_lesson.completed": CourseLessonCompletedEventData;
+  readonly "course_certificate.issued": CourseCertificateEventData;
+  readonly "course_certificate.revoked": CourseCertificateEventData;
+};
+/** The `courses` block's event types, for its manifest and `onBlockEvent`. */
+export declare const coursesEvents: Events<CoursesEvents>;
+//#endregion
+//#region src/blocks/courses/manifest.d.ts
+/** The `courses` block's manifest (ADR 0029). */
+export declare const coursesBlock: BlockOf<"courses", typeof createCourses, CoursesEvents>;
+//#endregion
+//#region src/blocks/courses/schemas.d.ts
+/** What `save` takes, with the bounds the SQL checks. */
+export declare const courseInputSchema: EntitySchema<CourseInput>;
+/** What `saveLesson` takes, with the bounds the SQL checks. */
+export declare const courseLessonInputSchema: EntitySchema<CourseLessonInput>;
+/** What the section's `enroll` and `unenroll` writes take. */
+interface CourseLearnerSectionInput {
+  /** The learner; the caller when left out. */
+  readonly userId?: string;
+}
+export declare const courseLearnerSectionInputSchema: EntitySchema<CourseLearnerSectionInput>;
+//#endregion
+//#region src/blocks/courses/section.d.ts
+/** The writes of the course learners section. */
+type CourseLearnersWrites = {
+  /** Enrolls a learner, or the caller, in the course. */
+  readonly enroll: SectionWrite<Courses, CourseLearnerSectionInput, CourseLearner>;
+  /** Cancels a learner's enrollment; their progress stays. */
+  readonly unenroll: SectionWrite<Courses, CourseLearnerSectionInput, CourseLearner>;
+};
+/** A course's learners with their progress, on the course's page. */
+export declare const courseLearnersSection: Section<Courses, readonly CourseLearner[], undefined, never, CourseLearnersWrites>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type Course, type CourseCertificate, type CourseCertificateCheck, type CourseCertificateEventData, type CourseEventData, type CourseInput, type CourseLearner, type CourseLearnerEventData, type CourseLearnerSectionInput, type CourseLearnerStatus, type CourseLearnersFilter, type CourseLearnersWrites, type CourseLesson, type CourseLessonCompletedEventData, type CourseLessonInput, type CourseLessonKind, type CourseLessonView, type CourseModule, type CourseModuleInput, type CourseOutline, type CourseOutlineLesson, type CourseOutlineModule, type CourseQuiz, type CourseQuizResult, type CourseStatus, type Courses, type CoursesEvents, type CoursesOptions, type CoursesSqlOptions, type LessonProgress, type RpcClient, coursesSqlOptions, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };