@valbuild/server 0.140.0 → 0.141.0

package/dist/declarations/src/videosetFixes.d.ts

@@ -0,0 +1,141 @@
+import { type ModuleFilePath, type SerializedRecordSchema, type SerializedSchema, type SerializedVideoSchema, type Source, type SourcePath, type ValidationError } from "@valbuild/core";
+import { type Patch } from "@valbuild/core/patch";
+import type { FixPatchRemainingError } from "./createFixPatch.js";
+import type { FixHandlerContext, FixHandlerResult, ModulePatch } from "./fixHandlers.js";
+import { type GalleryEntryKey } from "./galleryEntryKey.js";
+import type { Service } from "./Service.js";
+/** What of a `Service` the project-wide walks need. */
+export type VideoFieldService = Pick<Service, "getModuleFilePaths" | "get">;
+type ReadFile = (absolutePath: string) => Buffer | undefined;
+/** See `Internal.videosetEntryVideoSchema`: the Studio hashes against it too. */
+export declare function videosetEntryVideoSchema(record: SerializedRecordSchema): SerializedVideoSchema;
+/**
+ * Every file a set entry holds: its key's file and, for an HLS stream, every
+ * playlist and segment its master names — read from the LOCAL copy, which a
+ * remote entry promoted by `--fix` still has, and which is the only place a
+ * stream's tree can be followed from at all.
+ */
+export declare function filesOfVideosetEntry(entry: GalleryEntryKey, metadata: unknown, options: {
+    projectRoot: string;
+    readFile?: ReadFile;
+}): string[];
+/**
+ * The untracked files of a set's directory, sorted into the ones `--fix` can
+ * make entries of and the ones a person has to decide about.
+ *
+ * - `videos`: an untracked stream (keyed by its master playlist — the media
+ *   playlists and segments it names are part of it and listed nowhere), and a
+ *   progressive video the set accepts.
+ * - `others`: everything else — a poster or caption no video field names, a
+ *   media playlist without a master, a video of a type the set does not
+ *   accept. `--fix` does not add these: none of them is a video the set could
+ *   hold, and deleting someone's file is not a fix.
+ */
+export declare function classifyUntrackedVideosetFiles({ untracked, accept, projectRoot, readFile, }: {
+    untracked: string[];
+    accept: string;
+    projectRoot: string;
+    readFile?: ReadFile;
+}): {
+    videos: string[];
+    others: string[];
+};
+/**
+ * The files video fields name — a video of its own, and the poster and
+ * captions of every field — as `/public/…` refs, a remote one by the local
+ * path it was uploaded from.
+ */
+export declare function filesNamedByVideoFields(service: VideoFieldService, options: {
+    projectRoot: string;
+    readFile?: ReadFile;
+}): Promise<Set<string>>;
+/**
+ * The patches that point every `s.video(set)` field at a set entry's new key.
+ *
+ * One `add` on each field's `path`, so the description, poster, times and
+ * captions beside it are never rewritten. A field of another set, or of no
+ * set, is left alone even when its path is the same string: it names its own
+ * file.
+ */
+export declare function videosetReferencePatches(service: VideoFieldService, setModuleFilePath: ModuleFilePath, renamed: Record<string, string>): Promise<ModulePatch[]>;
+/**
+ * `videos:add-metadata`: the entry's KEY is its file, and it must be on disk
+ * (or on Val Remote, read over HTTP) and a kind Val can read the size and
+ * length of here — the same preconditions as `video:add-metadata`, asked of
+ * the key instead of `path`.
+ */
+export declare function handleVideosetMetadata(ctx: FixHandlerContext): Promise<FixHandlerResult>;
+/**
+ * `videos:check-remote`: a key that is wrong as a key — a remote URL in a set
+ * that is not `.remote()`, one that does not parse, one outside the set's
+ * directory. There is nothing to look up and nothing to move, so the error is
+ * reported as it is, for a person: only they know which of the set's options
+ * or the key is the mistake.
+ */
+export declare function handleVideosetCheckRemote(ctx: FixHandlerContext): Promise<FixHandlerResult>;
+/**
+ * `videos:upload-remote`: an entry of a `.remote()` set still keyed by a local
+ * path. Every file it holds goes up — a stream bottom-up, as the Studio places
+ * one — and `createFixPatch` renames the key to the ref, the same way
+ * `images:upload-remote` does. The fields that name the entry by its old key
+ * are rewritten too: without that they name a video the set no longer has.
+ *
+ * The entry's poster and captions — its defaults' files — go up with it, and
+ * are what is left to do for an entry whose key is already remote: the key
+ * stays, and the entry is written back with their refs.
+ */
+export declare function handleVideosetUploadRemote(ctx: FixHandlerContext): Promise<FixHandlerResult>;
+/**
+ * `videos:check-all-files`: the set's entries against its directory.
+ *
+ * What only this handler can answer is which untracked files are accounted
+ * for ELSEWHERE — a poster or caption a video field names — because that needs
+ * every module in the project. Those are fine. An untracked file that is not
+ * a video and that no field names is for a person to look at, and is reported
+ * here. Everything `--fix` can do something about — an entry whose file has
+ * gone, a video in the directory the set does not list — is left to
+ * `createFixPatch` (see {@link videosetCheckAllFilesPatch}), which reports it
+ * per entry, or repairs it.
+ */
+export declare function handleVideosetCheckAllFiles(ctx: FixHandlerContext): Promise<FixHandlerResult>;
+/**
+ * The `createFixPatch` half of `videos:check-all-files`: drop the entries
+ * whose file has gone, and add the videos in the directory that the set does
+ * not list — with what is read from their bytes, or not at all.
+ *
+ * What is stored for an entry that IS on disk is not compared against its
+ * bytes, unlike an image gallery's. The Studio reads a video's size and length
+ * in the browser from the file as it was picked, and that is not what a header
+ * parse of what is on disk says: a stream's largest rendition is not the
+ * upload's size whenever the upload was larger than the largest rendition, and
+ * two readers round a duration differently. Correcting one from the other
+ * would rewrite every streamed video in the project, every run. A missing
+ * value is `videos:add-metadata`'s, and is reported on the entry.
+ */
+export declare function videosetCheckAllFilesPatch({ projectRoot, apply, sourcePath, validationError, moduleSource, moduleSchema, }: {
+    projectRoot: string;
+    apply: boolean;
+    sourcePath: SourcePath;
+    validationError: ValidationError;
+    moduleSource: Source | undefined;
+    moduleSchema: SerializedSchema | undefined;
+}): Promise<{
+    patch: Patch;
+    remainingErrors: FixPatchRemainingError[];
+}>;
+/**
+ * The `createFixPatch` half of `videos:add-metadata`: read what is missing
+ * from the file at the entry's KEY, and write only that, one op per field —
+ * `alt` and anything already there are someone's, and stay.
+ */
+export declare function videosetAddMetadataPatch({ projectRoot, sourcePath, validationError, moduleSource, moduleSchema, }: {
+    projectRoot: string;
+    sourcePath: SourcePath;
+    validationError: ValidationError;
+    moduleSource: Source | undefined;
+    moduleSchema: SerializedSchema | undefined;
+}): Promise<{
+    patch: Patch;
+    remainingErrors: FixPatchRemainingError[];
+}>;
+export {};