@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

package/dist/tools/pages/schemas.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Page-tool output-schemas (Wave G.2 §4 structuredContent contracts).
+ *
+ * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1) so the
+ * handler files stay focused on logic.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+export declare const PAGES_LIST_OUTPUT_SCHEMA: z.ZodObject<{
+    items: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    total: z.ZodNumber;
+    etag: z.ZodOptional<z.ZodString>;
+    projected_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    available_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    unknown_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const SCHEMA_OUTPUT_SCHEMA: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        rel_path: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        element_type: z.ZodString;
+        label: z.ZodString;
+        has_binding: z.ZodBoolean;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    template_id: z.ZodString;
+}, z.core.$strip>;
+export declare const ETAG_OUTPUT_SCHEMA: z.ZodObject<{
+    etag: z.ZodString;
+    generated_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const TEMPLATE_SUMMARY_OUTPUT_SCHEMA: z.ZodObject<{
+    template_id: z.ZodString;
+    counts_by_type: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    bound_count: z.ZodNumber;
+    max_depth: z.ZodNumber;
+    total: z.ZodNumber;
+    named_sections: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    etag: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Input shape for `yootheme_builder_pages_create`.
+ *
+ * Mirrors the args of `POST /pages` (Phase B).
+ *
+ * Design pins:
+ *   - `post_type` is intentionally NOT exposed. Layer 9 defensive guard
+ *     on the REST side rejects it server-side; surfacing it at the MCP
+ *     boundary would invite a footgun where an agent tries to set it
+ *     and fails confusingly.
+ *   - `status` defaults to `draft` on the server (Q6 design — no public
+ *     empty page).
+ *   - `dry_run` triggers validation Layers 1+2+4 without persisting.
+ */
+export declare const PAGES_CREATE_INPUT: {
+    title: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        publish: "publish";
+        draft: "draft";
+        pending: "pending";
+        private: "private";
+        future: "future";
+    }>>;
+    layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+};
+/**
+ * Wire shape for `yootheme_builder_pages_create` on success (non-dry-run).
+ *
+ * Mirrors the REST 201 response shape.
+ *
+ * Design pins:
+ *   - `frontend_url` is nullable: REST returns null for fresh drafts
+ *     before publish.
+ *   - `template_id` is a plain string. The "page:{post_id}" prefix is
+ *     enforced server-side; adding a `.startsWith()` here would buy no
+ *     MCP-client value while adding Zod complexity.
+ *   - `warnings` is a lean string array (e.g. "slug_collision_resolved"
+ *     when WP auto-appends `-2`). The REST surface may expand this to
+ *     richer objects in v1.3; strings keep the v1.2 surface minimal.
+ */
+export declare const PAGES_CREATE_OUTPUT_SCHEMA: z.ZodObject<{
+    page_id: z.ZodOptional<z.ZodNumber>;
+    article_id: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodString;
+    slug: z.ZodString;
+    status: z.ZodString;
+    frontend_url: z.ZodNullable<z.ZodString>;
+    template_id: z.ZodString;
+    etag: z.ZodString;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Wire shape for `yootheme_builder_pages_create` when `dry_run:true`.
+ *
+ * Design pin: NO `etag` field. The B6 fix-cycle decision was that
+ * surfacing a "live" ETag with a dry-run response invites a stale-
+ * If-Match footgun (caller pins the ETag, then non-dry-run mutates,
+ * stale ETag rejected with 412). Dry-run is validation-only.
+ *
+ * `template_id_pattern` is a literal — the actual `template_id` cannot
+ * be materialised before WP allocates the post_id.
+ */
+export declare const PAGES_CREATE_DRY_RUN_OUTPUT_SCHEMA: z.ZodObject<{
+    dry_run: z.ZodLiteral<true>;
+    would_create: z.ZodObject<{
+        title: z.ZodString;
+        slug: z.ZodString;
+        status: z.ZodString;
+        template_id_pattern: z.ZodEnum<{
+            "page:{post_id}": "page:{post_id}";
+            "article:{article_id}": "article:{article_id}";
+        }>;
+    }, z.core.$strip>;
+    validation_report: z.ZodObject<{
+        layer_1_structural: z.ZodLiteral<"passed">;
+        layer_2_element_types: z.ZodLiteral<"passed">;
+        layer_4_renderer: z.ZodLiteral<"passed">;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Input shape for `yootheme_builder_pages_delete`.
+ *
+ * Mirrors the args of `DELETE /pages/{post_id}` (Phase B).
+ *
+ * Design pin: `confirm` is `z.literal(true)`. This is the Zod-side
+ * enforcement of the confirm gate — the MCP boundary rejects requests
+ * without `confirm:true` before they ever hit the REST layer.
+ *
+ * `force` defaults to false server-side → wp_delete_post(trash). When
+ * true → hard delete (irrecoverable).
+ */
+export declare const PAGES_DELETE_INPUT: {
+    post_id: z.ZodNumber;
+    confirm: z.ZodLiteral<true>;
+    force: z.ZodOptional<z.ZodBoolean>;
+};
+/**
+ * Wire shape for `yootheme_builder_pages_delete` on success.
+ *
+ * `deleted` is `z.literal(true)` — the success-response invariant. A
+ * failed delete surfaces as `isError:true` with a structured-error
+ * envelope, not as `deleted:false`.
+ */
+export declare const PAGES_DELETE_OUTPUT_SCHEMA: z.ZodObject<{
+    deleted: z.ZodLiteral<true>;
+    page_id: z.ZodOptional<z.ZodNumber>;
+    article_id: z.ZodOptional<z.ZodNumber>;
+    force_deleted: z.ZodBoolean;
+    etag: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/tools/pages/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,wBAAwB;;;;;;;iBA8BnC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAiB/B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAC;AAWH,eAAO,MAAM,8BAA8B;;;;;;;;;;;iBAazC,CAAC;AAWH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;CA6B9B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;iBAqBlC,CAAC;AAEN;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;iBAe7C,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;;CAiB9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;;;;;iBAYlC,CAAC"}

package/dist/tools/pages/schemas.js

@@ -0,0 +1,232 @@
+/**
+ * Page-tool output-schemas (Wave G.2 §4 structuredContent contracts).
+ *
+ * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1) so the
+ * handler files stay focused on logic.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+export const PAGES_LIST_OUTPUT_SCHEMA = z.object({
+    // F-Frontend-URL (2026-05-25): each row carries `frontend_url`,
+    // `frontend_url_template`, `frontend_url_description` so an MCP-agent
+    // can answer "What is the URL of my <type> template?" without a
+    // follow-up REST call or operator input. Server-side resolvers
+    // (WordPress: get_permalink/get_term_link/get_author_posts_url; Joomla:
+    // RouteHelper::getArticleRoute/getCategoryRoute/getTagRoute) emit one
+    // of two shapes per row:
+    //   - `frontend_url: <permalink>` + `frontend_url_template: null`
+    //     when a canonical public URL exists (latest post / first category
+    //     / first author etc.).
+    //   - `frontend_url: null` + `frontend_url_template: <pattern>` when
+    //     the URL needs a runtime parameter (search, 404-test) or when no
+    //     public content of the matching type exists yet.
+    // `frontend_url_description` is a short human hint ("Append any non-
+    // existent path to test." / "Latest published post — rendered with
+    // this template.") so the agent can render an instruction to the
+    // end-user. All three keys are kept on the row-record (not an extra
+    // schema object) so per-item sparse-field projection works.
+    items: z.array(z.record(z.string(), z.unknown())),
+    total: z.number(),
+    etag: z.string().optional(),
+    projected_fields: z.array(z.string()).optional(),
+    // F-004 fix (2026-05-25 exhaustive audit): projection-feedback —
+    // emitted ONLY when the caller passed `fields[]`. `available_fields`
+    // is the discovered top-level field vocabulary; `unknown_fields` is
+    // the subset of requested fields that did NOT appear in any item
+    // (previously: items came back as `[{}, {}, …]` silently).
+    available_fields: z.array(z.string()).optional(),
+    unknown_fields: z.array(z.string()).optional(),
+});
+export const SCHEMA_OUTPUT_SCHEMA = z.object({
+    // F-006 (2026-05-26): `rel_path` is the agent-preferred path form
+    // (matches `element_list` + `page_get_layout` emit). `path` (the
+    // fully-qualified `/templates/<id>/layout/...` pointer) stays on the
+    // row for back-compat but is optional so callers reading the schema
+    // know `rel_path` is the canonical projection column.
+    items: z.array(z.object({
+        rel_path: z.string(),
+        path: z.string().optional(),
+        element_type: z.string(),
+        label: z.string(),
+        has_binding: z.boolean(),
+    })),
+    total: z.number(),
+    template_id: z.string(),
+});
+export const ETAG_OUTPUT_SCHEMA = z.object({
+    etag: z.string(),
+    generated_at: z.string().optional(),
+});
+// F-AUDIT-2 (2026-05-26): template_summary outputSchema. The handler
+// passes the REST `/pages/{id}/summary` body through verbatim via
+// `jsonResult(data)`. Live shape verified against the WP+Joomla dev
+// hosts: `template_id`, `counts_by_type` (open-ended map element-type
+// → count), `bound_count`, `max_depth`, `total`, `named_sections` (each
+// `{path, name}`), and the `etag` string. NOTE: `_meta` is merged at
+// the RESULT-LEVEL by `withSiteMeta`, NEVER into `structuredContent`
+// (see results.ts W12-R2 commentary) — this schema therefore validates
+// only the inner template-summary shape.
+export const TEMPLATE_SUMMARY_OUTPUT_SCHEMA = z.object({
+    template_id: z.string(),
+    counts_by_type: z.record(z.string(), z.number().int().nonnegative()),
+    bound_count: z.number().int().nonnegative(),
+    max_depth: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    named_sections: z.array(z.object({
+        path: z.string(),
+        name: z.string(),
+    })),
+    etag: z.string(),
+});
+// ─── C1 — pages_create + pages_delete (v1.2) ──────────────────────────
+//
+// MCP tool schemas wrapping the Phase B REST endpoints:
+//   POST   /pages           → yootheme_builder_pages_create
+//   DELETE /pages/{post_id} → yootheme_builder_pages_delete
+//
+// These schemas drive (a) input validation at the MCP boundary and (b)
+// the structured-content outputSchema for client introspection.
+/**
+ * Input shape for `yootheme_builder_pages_create`.
+ *
+ * Mirrors the args of `POST /pages` (Phase B).
+ *
+ * Design pins:
+ *   - `post_type` is intentionally NOT exposed. Layer 9 defensive guard
+ *     on the REST side rejects it server-side; surfacing it at the MCP
+ *     boundary would invite a footgun where an agent tries to set it
+ *     and fails confusingly.
+ *   - `status` defaults to `draft` on the server (Q6 design — no public
+ *     empty page).
+ *   - `dry_run` triggers validation Layers 1+2+4 without persisting.
+ */
+export const PAGES_CREATE_INPUT = {
+    title: z
+        .string()
+        .min(1)
+        .describe('Page title (required, byte-equal stored in post_title).'),
+    slug: z
+        .string()
+        .optional()
+        .describe('Optional explicit slug; defaults to sanitize_title($title).'),
+    status: z
+        .enum(['publish', 'draft', 'pending', 'private', 'future'])
+        .optional()
+        .describe('Initial post status. Default: draft (Q6 design — no public empty page).'),
+    layout: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Optional initial YT layout. Default: {type:"layout",children:[]}.'),
+    dry_run: z
+        .boolean()
+        .optional()
+        .describe('When true, runs validation Layers 1+2+4 without persisting.'),
+    // post_type intentionally NOT exposed — Layer 9 defensive guard rejects
+    // it server-side. Exposing it would invite footgun attempts.
+};
+/**
+ * Wire shape for `yootheme_builder_pages_create` on success (non-dry-run).
+ *
+ * Mirrors the REST 201 response shape.
+ *
+ * Design pins:
+ *   - `frontend_url` is nullable: REST returns null for fresh drafts
+ *     before publish.
+ *   - `template_id` is a plain string. The "page:{post_id}" prefix is
+ *     enforced server-side; adding a `.startsWith()` here would buy no
+ *     MCP-client value while adding Zod complexity.
+ *   - `warnings` is a lean string array (e.g. "slug_collision_resolved"
+ *     when WP auto-appends `-2`). The REST surface may expand this to
+ *     richer objects in v1.3; strings keep the v1.2 surface minimal.
+ */
+export const PAGES_CREATE_OUTPUT_SCHEMA = z
+    .object({
+    // E1 cross-platform divergence: WP returns `page_id`, Joomla returns
+    // `article_id`. Both are positive ints; at least one is always present.
+    page_id: z.number().int().positive().optional(),
+    article_id: z.number().int().positive().optional(),
+    title: z.string(),
+    slug: z.string(),
+    status: z.string(),
+    frontend_url: z.string().nullable(),
+    template_id: z
+        .string()
+        .describe('Synthetic per-page template id, e.g. "page:3275" (WP) or "article:42" (Joomla).'),
+    etag: z.string(),
+    warnings: z
+        .array(z.string())
+        .describe('e.g. "slug_collision_resolved" when slug collision was resolved.'),
+})
+    .refine((v) => typeof v.page_id === 'number' || typeof v.article_id === 'number', { message: 'response must contain either page_id (WP) or article_id (Joomla)' });
+/**
+ * Wire shape for `yootheme_builder_pages_create` when `dry_run:true`.
+ *
+ * Design pin: NO `etag` field. The B6 fix-cycle decision was that
+ * surfacing a "live" ETag with a dry-run response invites a stale-
+ * If-Match footgun (caller pins the ETag, then non-dry-run mutates,
+ * stale ETag rejected with 412). Dry-run is validation-only.
+ *
+ * `template_id_pattern` is a literal — the actual `template_id` cannot
+ * be materialised before WP allocates the post_id.
+ */
+export const PAGES_CREATE_DRY_RUN_OUTPUT_SCHEMA = z.object({
+    dry_run: z.literal(true),
+    would_create: z.object({
+        title: z.string(),
+        slug: z.string(),
+        status: z.string(),
+        // E1 cross-platform divergence: WP returns 'page:{post_id}', Joomla returns 'article:{article_id}'.
+        template_id_pattern: z.enum(['page:{post_id}', 'article:{article_id}']),
+    }),
+    validation_report: z.object({
+        layer_1_structural: z.literal('passed'),
+        layer_2_element_types: z.literal('passed'),
+        layer_4_renderer: z.literal('passed'),
+    }),
+    // No `etag` field — by design (see B6 fix-cycle: stale-If-Match footgun).
+});
+/**
+ * Input shape for `yootheme_builder_pages_delete`.
+ *
+ * Mirrors the args of `DELETE /pages/{post_id}` (Phase B).
+ *
+ * Design pin: `confirm` is `z.literal(true)`. This is the Zod-side
+ * enforcement of the confirm gate — the MCP boundary rejects requests
+ * without `confirm:true` before they ever hit the REST layer.
+ *
+ * `force` defaults to false server-side → wp_delete_post(trash). When
+ * true → hard delete (irrecoverable).
+ */
+export const PAGES_DELETE_INPUT = {
+    post_id: z
+        .number()
+        .int()
+        .positive()
+        .describe('WP page post_id to delete.'),
+    confirm: z
+        .literal(true)
+        .describe('Must be true. Confirm gate prevents accidental deletes.'),
+    force: z
+        .boolean()
+        .optional()
+        .describe('If true, hard-deletes (wp_delete_post force=true). Default: trash (recoverable).'),
+};
+/**
+ * Wire shape for `yootheme_builder_pages_delete` on success.
+ *
+ * `deleted` is `z.literal(true)` — the success-response invariant. A
+ * failed delete surfaces as `isError:true` with a structured-error
+ * envelope, not as `deleted:false`.
+ */
+export const PAGES_DELETE_OUTPUT_SCHEMA = z
+    .object({
+    deleted: z.literal(true),
+    // E1 cross-platform divergence: WP returns page_id, Joomla returns article_id.
+    page_id: z.number().int().positive().optional(),
+    article_id: z.number().int().positive().optional(),
+    force_deleted: z.boolean(),
+    etag: z.string(),
+})
+    .refine((v) => typeof v.page_id === 'number' || typeof v.article_id === 'number', { message: 'response must contain either page_id (WP) or article_id (Joomla)' });
+//# sourceMappingURL=schemas.js.map

package/dist/tools/pages/schemas.js.map

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

package/dist/tools/pages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Backward-compat shim for `src/tools/pages.ts`.
+ *
+ * The original 358-LoC module was split into `src/tools/pages/`
+ * (5 files, each ≤ 200 LoC) per Architecture §11 cap (Round-2
+ * R2-A2-CRIT1 audit fix). This shim preserves the public import path
+ * (`from '../../src/tools/pages.js'`) so all existing test imports
+ * and `tools/index.ts` keep working unchanged.
+ *
+ * @license MIT
+ */
+export * from './pages/index.js';
+//# sourceMappingURL=pages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/tools/pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,kBAAkB,CAAC"}

package/dist/tools/pages.js

@@ -0,0 +1,13 @@
+/**
+ * Backward-compat shim for `src/tools/pages.ts`.
+ *
+ * The original 358-LoC module was split into `src/tools/pages/`
+ * (5 files, each ≤ 200 LoC) per Architecture §11 cap (Round-2
+ * R2-A2-CRIT1 audit fix). This shim preserves the public import path
+ * (`from '../../src/tools/pages.js'`) so all existing test imports
+ * and `tools/index.ts` keep working unchanged.
+ *
+ * @license MIT
+ */
+export * from './pages/index.js';
+//# sourceMappingURL=pages.js.map

package/dist/tools/pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.js","sourceRoot":"","sources":["../../src/tools/pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,kBAAkB,CAAC"}

package/dist/tools/pool-resolve-helper.d.ts

@@ -0,0 +1,83 @@
+/**
+ * W6.3 — shared helper for the per-handler `pool.resolve(site_id)`
+ * pattern.
+ *
+ * Every tool handler does the same dance:
+ *   1. Extract `site_id` from args (optional, undefined → default site).
+ *   2. Call `pool.resolve(site_id)`.
+ *   3. Translate `NoDefaultSiteError` / `UnknownSiteError` into a
+ *      structured `errorResult` so the agent can self-recover.
+ *   4. Hand back `{client, site}` for downstream use.
+ *
+ * Centralising the dance keeps the 24 handler bodies short and ensures
+ * the error wording stays consistent across the tool surface.
+ *
+ * @license MIT
+ */
+import { type ClientPool, type PoolResolution } from '../sites/client-pool.js';
+import type { ResolvedSite } from '../sites/registry.js';
+import type { RestClient } from '../client.js';
+import { type ToolResult } from './tool-builder.js';
+/**
+ * Discriminated union returned by {@link resolveSiteOrError}: callers
+ * check the `ok` boolean before destructuring. When `ok === false`,
+ * the `error` field is a fully-formed `ToolResult` ready to be
+ * returned from the handler verbatim (no further wrapping needed).
+ *
+ * The dual-channel shape lets handlers keep their flat top-level
+ * control flow:
+ *
+ *   const r = await resolveSiteOrError(pool, args.site_id);
+ *   if (!r.ok) return r.error;
+ *   const { client, site } = r;
+ *   // ... existing logic ...
+ *   return withSiteMeta(result, site);
+ */
+export type SiteResolution = {
+    readonly ok: true;
+    readonly client: PoolResolution['client'];
+    readonly site: PoolResolution['site'];
+} | {
+    readonly ok: false;
+    readonly error: ToolResult;
+};
+/**
+ * Resolve a site_id through the pool, translating the W4 typed errors
+ * into structured `ToolResult` envelopes. Non-typed errors (genuine
+ * fetch failures during the platform probe, secret-resolver crashes,
+ * etc.) re-throw so the handler's outer try/catch can shape them with
+ * domain-specific hints.
+ */
+export declare function resolveSiteOrError(pool: ClientPool, siteId: string | undefined): Promise<SiteResolution>;
+/**
+ * W12-R2A (A4-F3 / A5-S2) — resolve a site + execute a handler-body with
+ * a 1-shot 401 retry.
+ *
+ * Bearer-rotation use case: a site's bearer is revoked / rotated /
+ * expired AFTER the pool cached a {@link RestClient} for it. The next
+ * call returns HTTP 401. Without retry the agent has to be told
+ * "restart your client". With retry we drop the cached client (so the
+ * next `pool.resolve` re-runs `secretResolver.resolve`), then call the
+ * handler-body again exactly once. If the second attempt also returns
+ * 401, we surface a structured `bearer_invalid` error with an
+ * actionable hint pointing at `sites_test` / sites.json.
+ *
+ * Scope: deliberately ONE retry. A second 401 means the bearer is
+ * genuinely revoked at the source — looping forever wastes tokens and
+ * masks the real problem.
+ *
+ * The wrapper handles {@link NoDefaultSiteError} / {@link
+ * UnknownSiteError} via the same `resolveSiteOrError` envelope so
+ * call-sites don't have to duplicate the structured-error wording.
+ * Non-401 thrown errors propagate to the handler's outer try/catch
+ * (or the SDK boundary) untouched — only HTTP 401 triggers the retry
+ * / structured-error path.
+ *
+ * Usage (post-migration):
+ *
+ *   handler: async ({ site_id, ...rest }) =>
+ *     withSiteRetry(pool, site_id, async (client, site) =>
+ *       withSiteMeta(await handleX(makeDeps(client), rest), site)),
+ */
+export declare function withSiteRetry(pool: ClientPool, siteId: string | undefined, fn: (client: RestClient, site: ResolvedSite) => Promise<ToolResult>): Promise<ToolResult>;
+//# sourceMappingURL=pool-resolve-helper.d.ts.map

package/dist/tools/pool-resolve-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-resolve-helper.d.ts","sourceRoot":"","sources":["../../src/tools/pool-resolve-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACH,KAAK,UAAU,EAEf,KAAK,cAAc,EAEtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;CAAE,GACvG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACpC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAAC,cAAc,CAAC,CAqDzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,aAAa,CAC/B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,UAAU,CAAC,GACpE,OAAO,CAAC,UAAU,CAAC,CA8CrB"}