@aglyn/plugins-ai 1.0.0-beta.271 → 1.0.0-beta.272

package/src/lib/model/ai-site-import.d.ts

@@ -0,0 +1,302 @@
+/**
+ * @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 AiCreditRange } from './ai-credit-estimate';
+import type { AiJobItemLedger } from './ai-jobs.types';
+/** The job kind. */
+export declare const AI_SITE_IMPORT_KIND: "import";
+/** The input naming the proved domain the job brings in. */
+export declare const AI_SITE_IMPORT_DOMAIN_INPUT = "domain";
+/** The most pages one wave brings in. */
+export declare const AI_SITE_IMPORT_WAVE_PAGES = 10;
+/**
+ * The most pages one import reads, whatever the plan allows: an unlimited
+ * plan is still one crawl's worth, and the crawl's own time budget may stop
+ * sooner (the inventory then says so).
+ */
+export declare const AI_SITE_IMPORT_MAX_PAGES = 200;
+/** The fewest pages under one address prefix that make it a collection. */
+export declare const AI_SITE_IMPORT_COLLECTION_MIN = 3;
+/** The most photos brought in from one page. */
+export declare const AI_SITE_IMPORT_IMAGES_PER_PAGE = 8;
+/** The most characters of one page's text a wave keeps for its model answer. */
+export declare const AI_SITE_IMPORT_PAGE_TEXT_MAX_CHARS = 6000;
+/** The most sections one imported page is planned with. */
+export declare const AI_SITE_IMPORT_MAX_SECTIONS = 6;
+/** The most characters a section's name, a page's title or a label keeps. */
+export declare const AI_SITE_IMPORT_LABEL_MAX_CHARS = 60;
+/** A page with fewer words than this and no photo has nothing to bring in. */
+export declare const AI_SITE_IMPORT_MIN_WORDS = 5;
+/** The item ledger slot of the site's header and footer. */
+export declare const AI_SITE_IMPORT_FRAME_SLOT = "frame";
+/** The ceiling one imported page reserves: its answer pass and its listing pass, at 50 each. */
+export declare const AI_SITE_IMPORT_PAGE_CEILING_CREDITS = 100;
+/** The ceiling the header and footer reserve: one answer at 50. */
+export declare const AI_SITE_IMPORT_FRAME_CEILING_CREDITS = 50;
+/** The most left-out pages listed by address; the rest are counted. */
+export declare const AI_SITE_IMPORT_LEFT_OUT_LISTED = 60;
+/** A page the crawl read, as the inventory keeps it: no text, only what plans it. */
+export interface AiSiteImportListedPage {
+    url: string;
+    path: string;
+    title: string;
+    foundBy: 'home' | 'sitemap' | 'link';
+    words: number;
+    images: number;
+}
+export type AiSiteImportGroupKind = 'main' | 'collection';
+export interface AiSiteImportGroup {
+    /** `main`, or `c:<prefix>` for a collection. */
+    id: string;
+    label: string;
+    kind: AiSiteImportGroupKind;
+    /** Pages of the group the crawl read, kept or not. */
+    pages: number;
+}
+/** Why a page the site has is not brought in. */
+export type AiSiteImportLeftOutReason = 
+/** Past the site's room under its plan's page count. */
+'plan-limit'
+/** robots.txt keeps AglynBot off it. */
+ | 'robots'
+/** A sign-in page: refused outright. */
+ | 'login-form'
+/** No text and no photo: nothing to bring in. */
+ | 'empty'
+/** It could not be read: an error, no answer, or not a web page. */
+ | 'unreadable'
+/** Over the size one page may be. */
+ | 'too-large'
+/** It sends visitors to another website. */
+ | 'off-site';
+export declare const AI_SITE_IMPORT_LEFT_OUT_REASONS: readonly AiSiteImportLeftOutReason[];
+export interface AiSiteImportLeftOut {
+    url: string;
+    path: string;
+    title: string;
+    reason: AiSiteImportLeftOutReason;
+}
+/** A photo brought into the site's media library, as a page places it. */
+export interface AiSiteImportPhoto {
+    mediaId: string;
+    src: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+}
+/** What a wave's read found on one page, for its model answer. Never on the wire. */
+export interface AiSiteImportPageRead {
+    at: string;
+    title: string;
+    /** The page's text in order, cut to `AI_SITE_IMPORT_PAGE_TEXT_MAX_CHARS`; fenced only when a prompt reads it. */
+    text: string;
+    /** The page's sections, from its headings. */
+    sections: string[];
+    /** Its photos' addresses, at most `AI_SITE_IMPORT_IMAGES_PER_PAGE`. */
+    images: Array<{
+        url: string;
+        alt: string;
+    }>;
+}
+export interface AiSiteImportPage {
+    /** The item ledger slot: `p0`, `p1`, … */
+    slot: string;
+    url: string;
+    path: string;
+    title: string;
+    group: string;
+    wave: number;
+    /** The id the page's draft is written under, minted with the inventory. */
+    draftId: string;
+    /** The page's address on the new site. */
+    slug: string;
+    words: number;
+    images: number;
+    /** Filled by the wave's read; the text is cleared once the page is in. */
+    read?: AiSiteImportPageRead | null;
+    /** Set when the wave's read found the page cannot be brought in after all. */
+    refused?: AiSiteImportLeftOutReason | null;
+    /** Filled once the page's photos are in the library. */
+    photos?: {
+        brought: number;
+        /** Already in the library from an earlier page or import: the same file, never a second copy. */
+        reused: number;
+        skipped: number;
+        assets: AiSiteImportPhoto[];
+    } | null;
+}
+export type AiSiteImportWaveStatus = 'waiting' | 'running' | 'review' | 'done';
+export interface AiSiteImportWave {
+    index: number;
+    label: string;
+    /** The group the wave brings in; the first wave's is `main`. */
+    group: string;
+    slots: string[];
+    /** Whether the wave builds the site's header and footer first. */
+    frame: boolean;
+    status: AiSiteImportWaveStatus;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export interface AiSiteImportState {
+    domain: string;
+    /** The site's name, as Create site was given it: the header's name. */
+    siteName: string;
+    ownership: {
+        method: string | null;
+        provenAt: number | null;
+        detail: string | null;
+    };
+    readAt: string;
+    /** The plan's page count; `null` when it has none. */
+    pageLimit: number | null;
+    /** Pages the site already had when its import read the old site. */
+    existingPages: number;
+    /** Pages the crawl read. */
+    found: number;
+    /** Why the crawl stopped short of the whole site, or `null` when it did not. */
+    stoppedBy: string | null;
+    groups: AiSiteImportGroup[];
+    pages: AiSiteImportPage[];
+    waves: AiSiteImportWave[];
+    /** At most `AI_SITE_IMPORT_LEFT_OUT_LISTED`, by address. */
+    leftOut: AiSiteImportLeftOut[];
+    /** Every page left out, by reason, listed or not. */
+    leftOutCount: Partial<Record<AiSiteImportLeftOutReason, number>>;
+    /** The header and footer's draft id, built in the first wave; `null` when there are no main pages. */
+    frame: {
+        draftId: string;
+    } | null;
+    /** The Trust & Safety row this import is logged under. */
+    reviewId: string | null;
+}
+/** A collection's prefix for a page address: its first segment, a dated archive's `posts`; `null` for a top-level page. */
+export declare function aiSiteImportPrefix(path: string): string | null;
+/** "news-and-events" → "News and events". */
+export declare function aiSiteImportPrefixLabel(prefix: string): string;
+/**
+ * The inventory's groups, in the order they are brought in: the main pages,
+ * then each collection — one the home page's menu links first, in menu order,
+ * then the larger before the smaller.
+ */
+export declare function aiSiteImportGroups(pages: readonly AiSiteImportListedPage[], menu?: readonly string[]): {
+    groups: AiSiteImportGroup[];
+    groupOf: (page: AiSiteImportListedPage) => string;
+};
+/**
+ * The address a page takes on the new site: one segment, as every Aglyn page
+ * has, from the last segment of its old address; home is the root. Two pages
+ * that would take the same address are told apart by their collection, then
+ * by a number. The draft writer still makes it unique on the site itself.
+ */
+export declare function aiSiteImportSlug(path: string, taken: Set<string>): string;
+export interface AiSiteImportInventoryInput {
+    domain: string;
+    siteName: string;
+    ownership: AiSiteImportState['ownership'];
+    readAt: string;
+    pages: readonly AiSiteImportListedPage[];
+    /** Addresses the home page's menu links, in its order. */
+    menu: readonly string[];
+    /** What the crawl could not read, by reason. */
+    skipped: ReadonlyArray<{
+        url: string;
+        reason: AiSiteImportLeftOutReason;
+    }>;
+    /** Skips the crawl only counted. */
+    skippedOverflow?: number;
+    stoppedBy: string | null;
+    /** The plan's page count; `null` for none. */
+    pageLimit: number | null;
+    existingPages: number;
+    /** Mints one draft id; the inventory names every page's draft before any is written. */
+    mintId: () => string;
+    reviewId?: string | null;
+    wavePages?: number;
+}
+/**
+ * The site's inventory cut into waves, every page left out said with its
+ * reason. Pure: the step reads the site, this decides what comes in.
+ */
+export declare function aiSiteImportInventory(input: AiSiteImportInventoryInput): AiSiteImportState;
+/** The item ledger an inventory starts: the header and footer, then every page, all pending. */
+export declare function aiSiteImportLedger(state: AiSiteImportState): AiJobItemLedger[];
+export type AiSiteImportWork = {
+    kind: 'inventory';
+} | {
+    kind: 'start-wave';
+    wave: AiSiteImportWave;
+}
+/** Pages of the running wave its read did not reach before its clock ran out. */
+ | {
+    kind: 'read';
+    wave: AiSiteImportWave;
+    pages: AiSiteImportPage[];
+} | {
+    kind: 'frame';
+    wave: AiSiteImportWave;
+} | {
+    kind: 'images';
+    wave: AiSiteImportWave;
+    page: AiSiteImportPage;
+} | {
+    kind: 'page';
+    wave: AiSiteImportWave;
+    page: AiSiteImportPage;
+} | {
+    kind: 'close-wave';
+    wave: AiSiteImportWave;
+} | {
+    kind: 'done';
+};
+/** Whether an item is still to be built. */
+export declare function aiSiteImportItemOpen(items: readonly AiJobItemLedger[] | null | undefined, slot: string): boolean;
+/** The wave running now, else `null`. */
+export declare function aiSiteImportRunningWave(state: AiSiteImportState | null | undefined): AiSiteImportWave | null;
+/** The next wave a person may start, else `null`. */
+export declare function aiSiteImportNextWave(state: AiSiteImportState | null | undefined): AiSiteImportWave | null;
+/** The wave a person is reviewing, else `null`. */
+export declare function aiSiteImportReviewWave(state: AiSiteImportState | null | undefined): AiSiteImportWave | null;
+/** What the next pass of the step does. */
+export declare function aiSiteImportNextWork(state: AiSiteImportState | null | undefined, items: readonly AiJobItemLedger[] | null | undefined): AiSiteImportWork;
+/** A wave started: running, with what its read found on each page. */
+export declare function aiSiteImportWaveStarted(state: AiSiteImportState, index: number, at: string, reads: ReadonlyMap<string, AiSiteImportPageRead | AiSiteImportLeftOutReason>): AiSiteImportState;
+/** More of a running wave's pages, read now. */
+export declare function aiSiteImportPagesRead(state: AiSiteImportState, reads: ReadonlyMap<string, AiSiteImportPageRead | AiSiteImportLeftOutReason>): AiSiteImportState;
+/** A page's photos are in the library. */
+export declare function aiSiteImportPhotosIn(state: AiSiteImportState, slot: string, photos: NonNullable<AiSiteImportPage['photos']>): AiSiteImportState;
+/** A page is in: its text is no longer kept. */
+export declare function aiSiteImportPageSettled(state: AiSiteImportState, slot: string): AiSiteImportState;
+/** A wave is in: waiting for its review, or done when no wave follows it. */
+export declare function aiSiteImportWaveClosed(state: AiSiteImportState, index: number, at: string): AiSiteImportState;
+/** The state as the console reads it: every page's read text left off. */
+export declare function aiSiteImportWire(state: AiSiteImportState | null | undefined): AiSiteImportState | null;
+/**
+ * What bringing in this many pages costs, quoted before it starts (AGL-3976):
+ * each page an AI page as measured, its ceiling its two passes, and the
+ * site's header and footer once when the wave builds them.
+ */
+export declare function aiSiteImportCreditRange(pages: number, options?: {
+    frame?: boolean;
+}): AiCreditRange;
+/** A wave's quote: the pages it has still to bring in, and its header and footer while they are owed. */
+export declare function aiSiteImportWaveCreditRange(state: AiSiteImportState, wave: AiSiteImportWave, items?: readonly AiJobItemLedger[] | null): AiCreditRange;
+/** Why a page is not brought in, as a person reads it. */
+export declare const AI_SITE_IMPORT_LEFT_OUT_COPY: Readonly<Record<AiSiteImportLeftOutReason, string>>;
+/** "3 pages" / "1 page". */
+export declare function aiSiteImportPagesText(count: number): string;
+/** The review a finished wave parks on, or the first wave's go-ahead once the site is read. */
+export declare function aiSiteImportWaveMessage(state: AiSiteImportState, items: readonly AiJobItemLedger[] | null | undefined): string;