@wootsup/yt-builder-mcp 1.7.2 → 1.9.0

package/dist/tools/library.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Layout Library tools — browse + fetch + insert + save the YOOtheme Pro
+ * Library catalog (layouts / element presets), PLUS the Image Sourcing pair
+ * (Task D1) that fills layout image slots with real photography. Task 2
+ * (Layout Library, Spec #2) + Task 3 (Spec #3) + Task 6 (Spec #6) + Task 7
+ * (Spec #7) + Task D1 (Image Sourcing).
+ *
+ *   yootheme_builder_library_browse
+ *      → paginated, taxonomy-filtered catalog rows (tableResult — Wave G.2).
+ *   yootheme_builder_library_get
+ *      → a SINGLE item's full tree + derived section list (the natural next
+ *        call after library_browse — id comes straight off a browse row).
+ *   yootheme_builder_library_insert
+ *      → compose + persist a browsed/fetched item onto a page/template
+ *        through the REAL hardened write chain.
+ *   yootheme_builder_library_save_as
+ *      → the REVERSE direction: save a page/subtree INTO "My Layouts".
+ *   yootheme_builder_image_search
+ *      → search Unsplash / Pexels (real photography) or YOOtheme Pro Images
+ *        (curated decorative/background assets) — forwards to the SAME
+ *        `?key=<theme apikey>` proxy auth `library_browse` uses (Task A0-C1,
+ *        PHP `ImageSearchService`). Returns candidate rows; `total:0` means
+ *        no Library API key configured, mirroring browse's empty-catalog hint.
+ *   yootheme_builder_image_import
+ *      → sideload ONE chosen photo (typically a `full_url` from
+ *        image_search) into the site's own Media Library. Returns
+ *        `{imported:true, local_url}` to bind via element_update_settings,
+ *        or `{imported:false, reason}` on a caught failure (never a 500).
+ *
+ * browse/get/image_search are read-only forwards, exactly like the sibling
+ * L1 read tools (sources_list / template_summary / pages_list): resolve the
+ * site via the pool, GET the plugin REST endpoint, project into a table +
+ * strict structuredContent, stamp the result-level `_meta` (site_id/
+ * site_url/platform/resolved_via) via withSiteMeta. insert/save_as/
+ * image_import are WRITE forwards (withWriteSiteRetry — pre-flights a KNOWN
+ * read-only token before any body build, mirroring every other write tool's
+ * U2 pattern).
+ *
+ * ── Tiering (Task 7, deliberate) ─────────────────────────────────────────
+ * `library_save_as` is registered as an ADVANCED tool — it is NOT added to
+ * `ESSENTIAL_TOOLS` (essentials.ts) and does NOT appear as a first-class
+ * `tools/list` entry. `tools/list` sits close to the 28000B token-baseline
+ * ceiling (see `tests/perf/token-baseline.test.ts`); a 4th Layout-Library L1
+ * tool would risk busting it. `CapturingServer` (gateway/capturing-server.ts)
+ * automatically captures ANY registered tool whose name is absent from both
+ * `ESSENTIAL_TOOLS` and `DIRECT_TOP_LEVEL_TOOLS` into the L2 advanced
+ * registry — reachable via `yootheme_builder_advanced({tool, arguments})` —
+ * so simply NOT listing this name in essentials.ts is the entire tiering
+ * decision (mirrors how `yootheme_builder_clean_implode_directives` /
+ * `yootheme_builder_element_unbind_source` are advanced-only today). The
+ * name falls through the gateway's domain taxonomy (domains.ts) to "misc"
+ * (no `library` domain exists there) — intentional, NOT a bug (see
+ * `domain-order.test.ts`'s own pinned "misc" fallthrough cases): it keeps the
+ * gateway's own tools/list-visible description text from growing at all,
+ * while `{tool: "yootheme_builder_library_save_as"}` discovery and
+ * `{tool, arguments}` execution both remain fully reachable (the gateway
+ * dispatches by an exact Map lookup, independent of the domain-grouped
+ * DESCRIPTION text — see `gateway/advanced-tool/execute.ts`).
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import type { RestClient } from '../client.js';
+import type { ClientPool } from '../sites/client-pool.js';
+import { type AnyToolDefinition, type ToolResult } from './tool-builder.js';
+/**
+ * Fixed section-purpose enum (Task 8, Section Corpus Phase 1) — mirrors the
+ * PHP-side `SectionPurposeClassifier` / `SectionIndexEntry` purpose values
+ * byte-for-byte (design spec §A, Global Constraints). Only applies when
+ * `kind="section"`. Declared here (ahead of `LIBRARY_ITEM_SCHEMA`, which
+ * consumes it for the browse row's `purpose` field) rather than further
+ * down where the original Task 8 pass left it, since Task 8b (this file)
+ * now needs it at both the item-schema AND the browse-filter-schema sites.
+ */
+export declare const SECTION_PURPOSE_VALUES: readonly ["hero", "features", "stats", "team", "testimonial", "cta", "gallery", "pricing", "faq", "contact", "logos", "content"];
+export type SectionPurpose = (typeof SECTION_PURPOSE_VALUES)[number];
+/**
+ * Track 1 Task 7 (WootsUp AI Layouts) — the `source` axis for
+ * browse/get/insert: `"catalog"` (the remote YOOtheme Pro Library, the
+ * DEFAULT) or `"ai"` (the plugin's OWN isolated "WootsUp AI Layouts" store,
+ * saved via library_save_as, no apikey). Mirrors the PHP-side
+ * `LibrarySourceRegistry` keys byte-for-byte.
+ */
+declare const LIBRARY_SOURCE_VALUES: readonly ["catalog", "ai"];
+type LibrarySource = (typeof LIBRARY_SOURCE_VALUES)[number];
+/**
+ * Track 1 Task 7 (WootsUp AI Layouts) — the `destination` axis for
+ * library_save_as: `"ai"` (save INTO the isolated AI store, the DEFAULT) or
+ * `"native"` (the escape hatch — save into YOOtheme's native "My Layouts").
+ */
+declare const SAVE_DESTINATION_VALUES: readonly ["ai", "native"];
+type SaveDestination = (typeof SAVE_DESTINATION_VALUES)[number];
+export declare const LIBRARY_BROWSE_OUTPUT_SCHEMA: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            element: "element";
+            layout: "layout";
+            section: "section";
+        }>;
+        meta: z.ZodObject<{
+            topic: z.ZodNullable<z.ZodString>;
+            type: z.ZodNullable<z.ZodString>;
+            role: z.ZodNullable<z.ZodString>;
+            website: z.ZodNullable<z.ZodString>;
+            image: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        thumbnail_url: z.ZodNullable<z.ZodString>;
+        layout_id: z.ZodOptional<z.ZodString>;
+        section_index: z.ZodOptional<z.ZodNumber>;
+        purpose: z.ZodOptional<z.ZodEnum<{
+            content: "content";
+            gallery: "gallery";
+            hero: "hero";
+            features: "features";
+            stats: "stats";
+            team: "team";
+            testimonial: "testimonial";
+            cta: "cta";
+            pricing: "pricing";
+            faq: "faq";
+            contact: "contact";
+            logos: "logos";
+        }>>;
+        element_signature: z.ZodOptional<z.ZodString>;
+        visual_effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        topic: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        website: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        has_images: z.ZodOptional<z.ZodBoolean>;
+        image_count: z.ZodOptional<z.ZodNumber>;
+        element_count: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const LIBRARY_GET_OUTPUT_SCHEMA: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        element: "element";
+        layout: "layout";
+        section: "section";
+    }>;
+    name: z.ZodString;
+    version: z.ZodString;
+    tree: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    sections: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        name: z.ZodString;
+        path: z.ZodString;
+        element_count: z.ZodNumber;
+    }, z.core.$strip>>;
+    images_manifest_count: z.ZodNumber;
+}, z.core.$strip>;
+export declare const LIBRARY_INSERT_OUTPUT_SCHEMA: z.ZodObject<{
+    template_id: z.ZodString;
+    inserted_path: z.ZodString;
+    element_count: z.ZodNumber;
+    images_mode: z.ZodEnum<{
+        placeholder: "placeholder";
+        curated: "curated";
+    }>;
+    images_resolved: z.ZodObject<{
+        downloaded: z.ZodNumber;
+        placeholders: z.ZodNumber;
+    }, z.core.$strip>;
+    new_etag: z.ZodString;
+    frontend_url: z.ZodNullable<z.ZodString>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export interface LibraryHandlerDeps {
+    readonly client: RestClient;
+}
+export interface LibraryBrowseArgs {
+    kind?: 'layout' | 'element' | 'section';
+    source?: LibrarySource;
+    topic?: string;
+    type?: string;
+    role?: string;
+    website?: string;
+    element_type?: string;
+    purpose?: SectionPurpose;
+    has_effects?: boolean;
+    query?: string;
+    limit?: number;
+    cursor?: string;
+}
+export declare function handleLibraryBrowse({ client }: LibraryHandlerDeps, { kind, source, topic, type, role, website, element_type, purpose, has_effects, query, limit, cursor }: LibraryBrowseArgs): Promise<ToolResult>;
+export interface LibraryGetArgs {
+    id: string;
+    kind?: 'layout' | 'element' | 'section';
+    source?: LibrarySource;
+    include_thumbnail?: boolean;
+}
+export declare function handleLibraryGet({ client }: LibraryHandlerDeps, { id, kind, source, include_thumbnail }: LibraryGetArgs): Promise<ToolResult>;
+export type LibraryInsertTarget = {
+    new_page: {
+        title: string;
+        status?: string;
+    };
+} | {
+    sublayout: {
+        template_id: string;
+        element_path: string;
+    };
+} | {
+    template_id: string;
+    element_path?: string;
+};
+export interface LibraryInsertArgs {
+    id: string;
+    kind?: 'layout' | 'element' | 'section';
+    source?: LibrarySource;
+    target: LibraryInsertTarget;
+    section_index?: number;
+    images?: 'placeholder' | 'curated';
+    etag?: string;
+}
+export declare function handleLibraryInsert({ client }: LibraryHandlerDeps, { id, kind, source, target, section_index, images, etag }: LibraryInsertArgs): Promise<ToolResult>;
+export declare const LIBRARY_SAVE_AS_OUTPUT_SCHEMA: z.ZodObject<{
+    library_id: z.ZodString;
+    name: z.ZodString;
+    storage: z.ZodString;
+    invalid_source_possible: z.ZodBoolean;
+}, z.core.$strip>;
+export interface LibrarySaveAsArgs {
+    source: {
+        template_id: string;
+        element_path?: string;
+    };
+    name: string;
+    destination?: SaveDestination;
+}
+export declare function handleLibrarySaveAs({ client }: LibraryHandlerDeps, { source, name, destination }: LibrarySaveAsArgs): Promise<ToolResult>;
+declare const IMAGE_SOURCE_VALUES: readonly ["unsplash", "pexels", "proimages"];
+type ImageSource = (typeof IMAGE_SOURCE_VALUES)[number];
+export declare const IMAGE_SEARCH_OUTPUT_SCHEMA: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        source: z.ZodString;
+        thumb_url: z.ZodString;
+        full_url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        alt: z.ZodString;
+        author: z.ZodString;
+        author_url: z.ZodString;
+        orientation: z.ZodString;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    source: z.ZodString;
+    query: z.ZodString;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const IMAGE_IMPORT_OUTPUT_SCHEMA: z.ZodObject<{
+    imported: z.ZodBoolean;
+    local_url: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export interface ImageSearchArgs {
+    source?: ImageSource;
+    query: string;
+    per_page?: number;
+    orientation?: string;
+    color?: string;
+}
+export declare function handleImageSearch({ client }: LibraryHandlerDeps, { source, query, per_page, orientation, color }: ImageSearchArgs): Promise<ToolResult>;
+export interface ImageImportArgs {
+    url: string;
+}
+export declare function handleImageImport({ client }: LibraryHandlerDeps, { url }: ImageImportArgs): Promise<ToolResult>;
+export declare function buildLibraryTools(pool: ClientPool): readonly AnyToolDefinition[];
+export {};
+//# sourceMappingURL=library.d.ts.map

package/dist/tools/library.d.ts.map

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