@aglyn/plugins-ai 1.0.0-beta.246 → 1.0.0-beta.249

package/src/lib/jobs/ai-job-media-step.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { PluginAiCapabilityArgsSchema } from '@aglyn/aglyn/plugin-manager/plugin-ai-capabilities';
+import { getLockdownVerdict } from '@aglyn/tenant-data-admin/server/lockdown';
+import { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations';
+import { type Firestore } from 'firebase-admin/firestore';
+import { type AiJobAdmission } from './ai-job-admission';
+import type { AiJobStepRunner } from './ai-job-text-step';
+/**
+ * The `media` step (AGL-3752): organizing files already in a site's own media
+ * library — the folder each is filed in, its tags, its alt text and its name —
+ * as a first-class build operation, so "put the kiln photos in a Studio
+ * folder", "tag these portfolio" or "write the missing alt text" is one item
+ * on Assist's plan card.
+ *
+ * NO MODEL. The planner wrote the values as the item's arguments; this holds
+ * each to the rule the media library's own controls hold it to and writes it,
+ * so it costs no credits.
+ *
+ * ── Only the library's own fields ────────────────────────────────────────
+ *
+ * Exactly what the Details drawer and the grid's bulk actions write on a
+ * file's document: `fileName` (200), `alt` (`MEDIA_ALT_MAX_LENGTH`), `tags`
+ * (`normalizeMediaTags`: lower case, 20 of 40 characters), and `folderId`
+ * with the legacy `folder` name beside it, with the library's filter and
+ * search keys re-derived from the document as the write leaves it
+ * (`mediaFilterKeys`). A new folder is the New folder button's: a
+ * `mediaFolders` document made by `newMediaFolderDoc`, its name held by
+ * `normalizeFolderName`, unique among its siblings without case, at most
+ * `MEDIA_FOLDER_MAX_DEPTH` deep. Filing a file writes its folder as the
+ * drawer's save does; the stored object takes the folder's path the next time
+ * that folder is moved or renamed, as after a drawer save. Its address never
+ * changes, so no page that uses it breaks.
+ *
+ * NEVER: uploading, copying, replacing or deleting a file, its bytes or the
+ * details inside them, its sharing or privacy, renaming or deleting a folder,
+ * or anything in the organization's shared library (every site of the
+ * workspace uses it). Those are not arguments.
+ *
+ * ── Alt text ─────────────────────────────────────────────────────────────
+ *
+ * Alt text describes ONE image: `alt` is for one image the request says what
+ * it shows. `altFromDetails` writes a missing alt from what the library
+ * already holds about the image — its description, or the caption, headline
+ * or title inside the file — and names the images that hold none. Never the
+ * file name, which read aloud is worse than silence (`inheritedMediaAlt`).
+ * The library's alt is what a placement takes when the image is placed;
+ * placements made before keep their own.
+ *
+ * ── Who may ──────────────────────────────────────────────────────────────
+ *
+ * The rules' own for a site library (`canWriteHostContent`,
+ * `hostWritesFrozen`): a member with the admin, editor or author role, while
+ * no lockdown freezes the site, its org or the platform. Asked at the door,
+ * before the write, and the role again inside the transaction that writes.
+ *
+ * ── Idempotent ───────────────────────────────────────────────────────────
+ *
+ * One transaction reads the files and folders as they are stored and writes
+ * only what differs; a folder of the asked name is found before one is made.
+ * A pass asked again writes nothing.
+ */
+export declare const AI_MEDIA_KIND: "media";
+/** ASSUMED: the site, the org, up to 20 file lookups and one transaction. No model. */
+export declare const AI_JOB_MEDIA_STEP_MINIMUM_MS = 8000;
+export declare const AI_MEDIA_NO_SITE_COPY = "Open the site whose media library should change.";
+export declare const AI_MEDIA_ROLE_COPY = "Organizing the media library needs the admin, editor or author role on this site.";
+export declare const AI_MEDIA_LOCKED_COPY = "This site is not accepting changes right now.";
+export declare const AI_MEDIA_NOTHING_COPY = "The request named no file in the media library and no change this could make to it.";
+/** Where a person finds what the op changed. */
+export declare const AI_MEDIA_WHERE = "the site\u2019s Media library";
+/** The output's fixed id: one site's library, whatever changed. */
+export declare const AI_MEDIA_OUTPUT_ID = "library";
+/** The library's own limits, each from the control that edits the field. */
+export declare const AI_MEDIA_LIMITS: {
+    /** Files one item may name or select. */
+    readonly files: 20;
+    /** The Details drawer's file name. */
+    readonly fileName: 200;
+    readonly alt: 300;
+    readonly tags: 20;
+    readonly tag: 40;
+    /** A folder path: five names of 60 and their separators. */
+    readonly folder: number;
+};
+/** The item's arguments, as the planner fills them in. */
+export declare const AI_MEDIA_ARGS_SCHEMA: PluginAiCapabilityArgsSchema;
+/** What an item asks, each value read and held to the library's rule. */
+export interface AiMediaRequest {
+    files: string[];
+    missingAlt: boolean;
+    /** The folder path's names, root first. */
+    folder?: string[];
+    addTags: string[];
+    removeTags: string[];
+    rename?: string;
+    alt?: string;
+    altFromDetails: boolean;
+}
+export interface AiMediaRead {
+    request: AiMediaRequest;
+    problems: string[];
+}
+/** A folder path's names, root first, or a sentence saying why it cannot be one. */
+export declare function aiMediaFolderPathOf(value: string): string[] | {
+    error: string;
+};
+/** Why this alt text describes nothing, or `null`. */
+export declare function aiMediaAltProblem(alt: string, fileName: string): string | null;
+/** The item's arguments read: what may be written, and a sentence for each that may not. */
+export declare function aiMediaRequestOf(inputs: Readonly<Record<string, unknown>> | null | undefined): AiMediaRead;
+/** Whether a read request names files and a change to make to them. */
+export declare function aiMediaRequestEmpty(request: AiMediaRequest): boolean;
+/** A site library row, as the op reads it. */
+export interface AiMediaRow {
+    id: string;
+    /** The document as stored, which the filter keys are derived from. */
+    data: Record<string, unknown>;
+}
+/** A media folder, as the op reads it. */
+export interface AiMediaFolderRow {
+    id: string;
+    name: string;
+    parentId: string | null;
+}
+/**
+ * The file a name or id names among the rows read from the site's library:
+ * never a deleted one. Its id wins over a file name; two files of one name
+ * are refused in words.
+ */
+export declare function aiMediaFileOf(source: string, rows: readonly AiMediaRow[]): AiMediaRow | {
+    error: string;
+};
+/**
+ * Alt text written from what the library already holds about an image: its
+ * own description, else the caption, headline or title read from inside the
+ * file (only while that record still describes the file's bytes). `null`
+ * when it holds none that says what the image shows.
+ */
+export declare function aiMediaAltFromDetails(row: AiMediaRow): string | null;
+/** A folder to make: its name, and its parent's id or its index among those made before it. */
+export interface AiMediaFolderCreate {
+    name: string;
+    parent: {
+        id: string | null;
+    } | {
+        made: number;
+    };
+}
+/**
+ * Where a folder path lands: the existing folders it walks, matched without
+ * case among siblings as the library's sibling rule matches them, and the
+ * folders left to make below the last one found.
+ */
+export declare function aiMediaFolderPlan(path: readonly string[], folders: readonly AiMediaFolderRow[]): {
+    existingId: string | null;
+    create: AiMediaFolderCreate[];
+};
+/** One file's change: the fields to write and the sentences that say it. */
+export interface AiMediaFileChange {
+    update: Record<string, unknown>;
+    said: string[];
+    notDone: string[];
+}
+/**
+ * What the request changes on one file, compared with what is stored: only
+ * the fields that differ, with the filter keys re-derived from the document
+ * as the change leaves it, exactly as the Details drawer derives them.
+ */
+export declare function aiMediaFileChange(row: AiMediaRow, request: AiMediaRequest, folder: {
+    id: string;
+    name: string;
+} | null): AiMediaFileChange;
+export type AiMediaWrite = {
+    ok: true;
+    done: string[];
+    notDone: string[];
+    changedFiles: number;
+    madeFolders: string[];
+    altChanged: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The library change, written in one transaction that reads the site, its
+ * folders and the named files as they are stored NOW: the member still holds
+ * a write role, a folder of the asked name is used before one is made, and
+ * only fields that differ are written.
+ */
+export declare function writeAiMediaChanges(firestore: Firestore, input: {
+    hostId: string;
+    uid: string;
+    request: AiMediaRequest;
+    now: Date;
+}): Promise<AiMediaWrite>;
+/** Why this member may not organize this site's library now, or `null`. */
+export declare function aiMediaAccessRefusal(input: {
+    host: FirebaseFirestore.DocumentSnapshot;
+    uid: string;
+    org: object | null;
+}, deps?: {
+    lockdown?: typeof getLockdownVerdict;
+}): Promise<string | null>;
+/** The output's note: what changed, that it is live, and what was not done. */
+export declare function aiMediaOutputNote(done: readonly string[], notDone: readonly string[], altChanged: boolean): string;
+export interface AiJobMediaStepDeps {
+    write?: typeof writeAiMediaChanges;
+    lockdown?: typeof getLockdownVerdict;
+}
+export declare function createAiJobMediaStep(deps?: AiJobMediaStepDeps): AiJobStepRunner;
+export declare const runAiJobMediaStep: AiJobStepRunner;
+export interface AiMediaJobAdmissionDeps {
+    ownerOf?: typeof resolveOrgIdForHost;
+    lockdown?: typeof getLockdownVerdict;
+}
+/**
+ * A library change is admitted on a site of the job's own org, for a member
+ * who may write its library now, where the request names files and a change
+ * this can make. Refused in those words before anything is written.
+ */
+export declare function createAiMediaJobAdmission(deps?: AiMediaJobAdmissionDeps): AiJobAdmission;
+export declare const aiMediaJobAdmission: AiJobAdmission;
+/** Registers the media library step and its door (AGL-3752). */
+export declare function registerAiMediaJob(): void;