@happyvertical/smrt-education 0.58.0 → 0.59.1

package/dist/sources/class-crunchlabs.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Class CrunchLabs unit downloads to a course bundle (SMRT #4616).
+ *
+ * A unit download is a folder (or the zip parts a Drive export splits it into)
+ * holding `<Unit>_All Unit Wide Materials` and `<Unit>_Lesson <n>` folders. Files
+ * are lettered: A teacher manual, B slides, C student mission log, D status check
+ * assessment (plus guidance, editable), E handouts, F extras, G videos. The
+ * videos are not read: their names (`Lnn.step_Video_Kind_Title`) are matched,
+ * by unit, lesson and step, to the unit's YouTube course playlist and become
+ * external references.
+ *
+ * `buildClassCrunchLabsBundle` reads such a download and returns a manifest
+ * version 2 bundle for `CourseBundleImportService`. Nothing here touches the
+ * network: the playlist comes from an injected `ClassCrunchLabsPlaylistSource`,
+ * and files from an injected `ClassCrunchLabsFileSource` (Node folder and zip
+ * readers are in `class-crunchlabs-files.ts`). The files are CrunchLabs' own
+ * downloads, never hosted by us.
+ */
+import type { DocumentConverter, OfficeDocumentKind } from '../document-converter.js';
+export declare const CLASS_CRUNCHLABS_PROVIDER_ID: "class-crunchlabs";
+export declare const CLASS_CRUNCHLABS_SUBJECT = "Science";
+/** The licence a family's own copy of a CrunchLabs unit carries. */
+export declare const CLASS_CRUNCHLABS_LICENSE_KIND: "personal-use-copy";
+export declare class ClassCrunchLabsError extends Error {
+    readonly code: 'no_unit' | 'multiple_units' | 'empty_unit' | 'too_large' | 'access_denied';
+    readonly detail: readonly string[];
+    constructor(code: 'no_unit' | 'multiple_units' | 'empty_unit' | 'too_large' | 'access_denied', message: string, detail?: readonly string[]);
+}
+/** One file of a unit download. Bytes are read lazily, and only for files that are used. */
+export interface ClassCrunchLabsFile {
+    /** Path inside its source (folder-relative, or the zip entry name). */
+    path: string;
+    size: number;
+    /** CRC-32 (lower-case hex) when known without reading, used to spot repeated exports. */
+    crc32?: string;
+    /** Orders repeated exports of the same unit: the larger value is the newer export. */
+    exportId?: string;
+    read(): Promise<Uint8Array>;
+}
+export interface ClassCrunchLabsFileSource {
+    files(): Promise<ClassCrunchLabsFile[]>;
+}
+/** An in-memory source (tests, or a host that already holds the files). */
+export declare function memoryClassCrunchLabsSource(files: ReadonlyArray<{
+    path: string;
+    bytes?: Uint8Array;
+    size?: number;
+    exportId?: string;
+    crc32?: string;
+}>): ClassCrunchLabsFileSource;
+export interface ClassCrunchLabsPlaylistItem {
+    videoId: string;
+    title: string;
+    position: number;
+}
+/** A YouTube course playlist of the @ClassCrunchLabs channel. */
+export interface ClassCrunchLabsPlaylist {
+    id: string;
+    title: string;
+    /** The unit the playlist belongs to when the source knows it; else derived from the title. */
+    unit?: string;
+    items: ClassCrunchLabsPlaylistItem[];
+}
+/** Injected: tests use fixtures, a host fetches the channel's playlists. Never called from a test with a network. */
+export interface ClassCrunchLabsPlaylistSource {
+    playlists(): Promise<ClassCrunchLabsPlaylist[]>;
+}
+export type ClassCrunchLabsPageCounter = (input: {
+    bytes: Uint8Array;
+    kind: 'pdf' | OfficeDocumentKind;
+}) => Promise<number | null>;
+/** Case, punctuation and spacing insensitive key. */
+export declare const classCrunchLabsKey: (value: string) => string;
+export interface ClassCrunchLabsVideoName {
+    lesson: number;
+    /** Lower-case step such as `6` or `1b`. */
+    step: string;
+    /** The kind token as named, for example `MaterialsPrep`. */
+    kind: string;
+    /** Humanized title, `''` when the name has none. */
+    title: string;
+}
+/** Parse `Lnn.step_Video_Kind_Title_Unit.mp4`; null when the name is not a lesson video. */
+export declare function parseClassCrunchLabsVideoName(fileName: string, unit: string): ClassCrunchLabsVideoName | null;
+export interface ClassCrunchLabsVideoMatch {
+    lesson: number;
+    step: string;
+    kind: string;
+    title: string;
+    videoId: string;
+    playlistItem: string;
+}
+export interface ClassCrunchLabsVideoMiss {
+    lesson: number;
+    step: string;
+    kind: string;
+    title: string;
+    reason: 'no_playlist' | 'no_item' | 'ambiguous' | 'item_taken';
+}
+/** The (lesson, step) a playlist item title names: `L03.6`, `Lesson 3 ... Step 6`. */
+export declare function parsePlaylistItemTitle(title: string): {
+    lesson: number;
+    step: string;
+} | null;
+/** The playlist for a unit: its title (or `unit`) names the unit; the shortest title wins. */
+export declare function pickUnitPlaylist(playlists: readonly ClassCrunchLabsPlaylist[], unit: string): ClassCrunchLabsPlaylist | null;
+/**
+ * Match lesson videos to playlist items by lesson and step. Two videos that
+ * share a step (a materials-prep and a hands-on video) are told apart by the
+ * item title naming their title or kind; if that cannot decide, they are left
+ * unmatched as `ambiguous` rather than guessed. Each item is used once.
+ */
+export declare function matchClassCrunchLabsVideos(videos: readonly ClassCrunchLabsVideoName[], playlist: ClassCrunchLabsPlaylist | null): {
+    matched: ClassCrunchLabsVideoMatch[];
+    unmatched: ClassCrunchLabsVideoMiss[];
+    unusedItems: number;
+};
+export interface ClassCrunchLabsBuildOptions {
+    files: ClassCrunchLabsFileSource;
+    /** Without one, videos are reported unmatched (`no_playlist`) and no reference is written. */
+    playlists?: ClassCrunchLabsPlaylistSource;
+    /** Which unit when the download holds several; matched ignoring case and punctuation. */
+    unit?: string;
+    /**
+     * How many pages a mission log has, to write its lesson page range. Without
+     * one, or when it returns null, the lesson gets no page rows (a warning says so).
+     */
+    pageCounter?: ClassCrunchLabsPageCounter;
+    /**
+     * The unit-wide "(all lessons)" files (the combined manual, deck, mission log,
+     * status checks and handouts) repeat the per-lesson files and are large, so they
+     * are left out by default. The supply list, posters and other unit-wide extras
+     * are always course members.
+     */
+    includeUnitWideAggregates?: boolean;
+    /** Largest bundle part in bytes; default 90 MiB, never above the bundle archive limit. */
+    maxPartBytes?: number;
+}
+export interface ClassCrunchLabsReport {
+    unit: string;
+    lessons: number;
+    members: number;
+    courseMembers: number;
+    /** Bundles the unit was split into (1 unless it is large). */
+    parts: number;
+    pages: Array<{
+        lesson: number;
+        path: string;
+        pages: number;
+    }>;
+    videos: {
+        playlist: {
+            id: string;
+            title: string;
+        } | null;
+        matched: ClassCrunchLabsVideoMatch[];
+        unmatched: ClassCrunchLabsVideoMiss[];
+        unusedPlaylistItems: number;
+        /** Unit-level videos (a teaser): a course has no video of its own, so none is written. */
+        unitLevel: string[];
+    };
+    /** Same bytes under another name or place: only the preferred copy is bundled. */
+    duplicates: Array<{
+        path: string;
+        duplicateOf: string;
+    }>;
+    /** The same file in more than one export of the unit. */
+    duplicateExports: number;
+    /** A file that differs between exports: the newer export is used. */
+    superseded: number;
+    ignored: Array<{
+        path: string;
+        reason: string;
+    }>;
+    warnings: string[];
+}
+/** One importable bundle: a manifest version 2 and the files it names. */
+export interface ClassCrunchLabsBundlePart {
+    bundle: {
+        files: Array<{
+            path: string;
+            bytes: Uint8Array;
+        }>;
+    };
+    manifest: Record<string, unknown>;
+    /** The lesson numbers this part carries. */
+    lessons: number[];
+}
+export interface ClassCrunchLabsBuild {
+    unit: string;
+    /**
+     * The bundles to import, in order, each with `CourseBundleImportService`. A
+     * unit that fits one archive is one part; a large one is split by lesson
+     * (course-level members go in the first part), never by file.
+     */
+    parts: ClassCrunchLabsBundlePart[];
+    /** The first part, for the usual single-bundle unit. */
+    bundle: ClassCrunchLabsBundlePart['bundle'];
+    manifest: Record<string, unknown>;
+    /** A family's own copy of a unit is a personal-use copy. */
+    licenseKind: typeof CLASS_CRUNCHLABS_LICENSE_KIND;
+    report: ClassCrunchLabsReport;
+}
+/** Read a Class CrunchLabs unit download and build a manifest version 2 bundle. */
+export declare function buildClassCrunchLabsBundle(options: ClassCrunchLabsBuildOptions): Promise<ClassCrunchLabsBuild>;
+/**
+ * A page counter for mission logs: PDFs are counted directly (`pdf-lib`), Word
+ * and PowerPoint files by asking the injected converter to render them. Without
+ * a converter, only PDFs are counted. The count is a convenience for the page
+ * range; the importer still renders the member itself.
+ */
+export declare function createClassCrunchLabsPageCounter(options?: {
+    converter?: DocumentConverter;
+    timeoutMs?: number;
+    maxBytes?: number;
+}): ClassCrunchLabsPageCounter;
+//# sourceMappingURL=class-crunchlabs.d.ts.map

package/dist/sources/class-crunchlabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"class-crunchlabs.d.ts","sourceRoot":"","sources":["../../src/sources/class-crunchlabs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-education",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "smrtJsdoc": "strict",
   "description": "Tenant-aware learning catalog models and authorized catalog access for SMRT",
   "type": "module",
@@ -22,21 +22,25 @@
     "./ingestion": {
       "types": "./dist/ingestion.d.ts",
       "import": "./dist/ingestion.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
     }
   },
   "dependencies": {
-    "@happyvertical/smrt-assets": "0.58.0",
-    "@happyvertical/smrt-core": "0.58.0",
-    "@happyvertical/smrt-profiles": "0.58.0",
-    "@happyvertical/smrt-tenancy": "0.58.0",
-    "@happyvertical/smrt-users": "0.58.0",
+    "@happyvertical/smrt-assets": "0.59.1",
+    "@happyvertical/smrt-core": "0.59.1",
+    "@happyvertical/smrt-profiles": "0.59.1",
+    "@happyvertical/smrt-tenancy": "0.59.1",
+    "@happyvertical/smrt-users": "0.59.1",
     "@happyvertical/files": "^0.111.3",
     "@happyvertical/sql": "^0.111.3",
     "pdf-lib": "1.17.1",
-    "@happyvertical/smrt-ingestion": "0.58.0"
+    "@happyvertical/smrt-ingestion": "0.59.1"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.58.0",
+    "@happyvertical/smrt-vitest": "0.59.1",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
     "vite": "8.1.6",