emdash-plugin-avdeb 0.1.0

package/src/client.ts

@@ -0,0 +1,304 @@
+/**
+ * Cached AVDEB catalog client.
+ *
+ * Every query is cached in plugin KV on its own. When AVDEB can't be reached the last good answer
+ * (kept for a week) is served and retried after a back-off. Because the render route is public,
+ * network calls are also capped per minute so nobody can burn the site's API quota by sending
+ * random queries. Pure module: KV and fetch are injected.
+ */
+
+import {
+	apiErrorMessage,
+	parseKeyResponse,
+	parseProductsResponse,
+	productsUrl,
+	queryKey,
+	type CatalogQuery,
+	type KeyOwner,
+	type Product,
+	type Tier,
+} from "./catalog.ts";
+import { API_BASE, VERSION } from "./constants.ts";
+
+export interface KVLike {
+	get<T>(key: string): Promise<T | null>;
+	set(key: string, value: unknown): Promise<void>;
+	delete(key: string): Promise<boolean>;
+	list(prefix?: string): Promise<Array<{ key: string; value: unknown }>>;
+}
+
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+export interface LogLike {
+	warn(message: string, data?: unknown): void;
+}
+
+export interface ClientOptions {
+	kv: KVLike;
+	fetch: FetchLike;
+	apiKey: string;
+	refCode: string;
+	cacheMinutes: number;
+	now?: () => number;
+	/** Max network calls per minute across all queries (default 30). */
+	budgetPerMinute?: number;
+	timeoutMs?: number;
+	log?: LogLike;
+}
+
+export type ProductsSource = "cache" | "network" | "stale" | "empty";
+
+export interface ProductsOutcome {
+	products: Product[];
+	ref: string;
+	tier: Tier;
+	source: ProductsSource;
+	error?: string;
+}
+
+export type KeyInfo = { ok: true; owner: KeyOwner } | { ok: false; error: string };
+
+export interface ClientStats {
+	requests: number;
+	errors: number;
+	lastFetchAt: number | null;
+	lastError: string | null;
+	lastErrorAt: number | null;
+	cachedQueries: number;
+	cacheVersion: number;
+}
+
+interface ProductsEntry {
+	key: string;
+	products: Product[];
+	ref: string;
+	tier: Tier;
+	fetchedAt: number;
+	freshUntil: number;
+	staleUntil: number;
+	error?: string;
+}
+
+interface KeyEntry {
+	info: KeyInfo;
+	until: number;
+}
+
+interface StoredStats {
+	requests: number;
+	errors: number;
+	lastFetchAt: number | null;
+	lastError: string | null;
+	lastErrorAt: number | null;
+}
+
+const MINUTE = 60_000;
+export const STALE_MS = 7 * 24 * 60 * MINUTE;
+export const BACKOFF_MS = 15 * MINUTE;
+export const EMPTY_BACKOFF_MS = 5 * MINUTE;
+export const KEY_OK_MS = 10 * MINUTE;
+export const KEY_FAIL_MS = 5 * MINUTE;
+
+const K_VERSION = "state:version";
+const K_BUDGET = "state:budget";
+const K_STATS = "state:stats";
+const P_PRODUCTS = "cache:p:";
+const P_KEY = "cache:key:";
+
+/** FNV-1a (32-bit) as hex — short, stable KV key suffix. Entries also store the full key. */
+export function hash(input: string): string {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < input.length; i++) {
+		h ^= input.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function createCatalogClient(opts: ClientOptions) {
+	const now = opts.now ?? Date.now;
+	const kv = opts.kv;
+	const budget = opts.budgetPerMinute ?? 30;
+	const cacheMs = Math.max(5, opts.cacheMinutes) * MINUTE;
+	const identity = opts.apiKey ? `k:${hash(opts.apiKey)}` : `r:${opts.refCode}`;
+
+	function headers(): Record<string, string> {
+		const h: Record<string, string> = {
+			Accept: "application/json",
+			"User-Agent": `emdash-plugin-avdeb/${VERSION}`,
+		};
+		if (opts.apiKey) h.Authorization = `Bearer ${opts.apiKey}`;
+		return h;
+	}
+
+	async function request(url: string): Promise<{ ok: true; json: unknown } | { ok: false; error: string }> {
+		try {
+			const init: RequestInit = { method: "GET", headers: headers() };
+			if (typeof AbortSignal !== "undefined" && "timeout" in AbortSignal) {
+				init.signal = AbortSignal.timeout(opts.timeoutMs ?? 8000);
+			}
+			const res = await opts.fetch(url, init);
+			const json: unknown = await res.json().catch(() => null);
+			return res.ok ? { ok: true, json } : { ok: false, error: apiErrorMessage(res.status, json) };
+		} catch (err) {
+			return { ok: false, error: err instanceof Error ? err.message : String(err) };
+		}
+	}
+
+	async function version(): Promise<number> {
+		const v = await kv.get<number>(K_VERSION);
+		return typeof v === "number" && v > 0 ? v : 1;
+	}
+
+	/** Approximate per-minute limiter (KV round-trips are not atomic; good enough as a quota guard). */
+	async function takeBudget(): Promise<boolean> {
+		const minute = Math.floor(now() / MINUTE);
+		const cur = await kv.get<{ minute: number; count: number }>(K_BUDGET);
+		const count = cur && cur.minute === minute ? cur.count : 0;
+		if (count >= budget) return false;
+		await kv.set(K_BUDGET, { minute, count: count + 1 });
+		return true;
+	}
+
+	async function record(error: string | null): Promise<void> {
+		const prev = (await kv.get<StoredStats>(K_STATS)) ?? {
+			requests: 0,
+			errors: 0,
+			lastFetchAt: null,
+			lastError: null,
+			lastErrorAt: null,
+		};
+		const t = now();
+		await kv.set(K_STATS, {
+			requests: prev.requests + 1,
+			errors: prev.errors + (error ? 1 : 0),
+			lastFetchAt: t,
+			lastError: error ?? prev.lastError,
+			lastErrorAt: error ? t : prev.lastErrorAt,
+		} satisfies StoredStats);
+	}
+
+	async function products(query: CatalogQuery): Promise<ProductsOutcome> {
+		const key = `${identity}|${queryKey(query)}`;
+		const id = `${P_PRODUCTS}${await version()}:${hash(key)}`;
+		const stored = await kv.get<ProductsEntry>(id);
+		const entry = isRecord(stored) && stored.key === key ? stored : null;
+		const t = now();
+
+		if (entry && t < entry.freshUntil) {
+			return { products: entry.products, ref: entry.ref, tier: entry.tier, source: "cache", error: entry.error };
+		}
+
+		const fallbackTier: Tier = opts.apiKey ? "secret" : "anonymous";
+		if (!(await takeBudget())) {
+			return entry && t < entry.staleUntil
+				? { products: entry.products, ref: entry.ref, tier: entry.tier, source: "stale", error: "rate limited" }
+				: { products: [], ref: "", tier: fallbackTier, source: "empty", error: "rate limited" };
+		}
+
+		const res = await request(productsUrl(query, opts.apiKey ? "" : opts.refCode));
+		const parsed = res.ok ? parseProductsResponse(res.json) : null;
+		const error = res.ok ? (parsed ? null : "Unexpected response from AVDEB") : res.error;
+		await record(error);
+
+		if (parsed) {
+			const ref = parsed.ref || (opts.apiKey ? "" : opts.refCode);
+			await kv.set(id, {
+				key,
+				products: parsed.products,
+				ref,
+				tier: parsed.tier,
+				fetchedAt: t,
+				freshUntil: t + cacheMs,
+				staleUntil: t + STALE_MS,
+			} satisfies ProductsEntry);
+			return { products: parsed.products, ref, tier: parsed.tier, source: "network" };
+		}
+
+		opts.log?.warn("AVDEB catalog request failed", { error, query });
+		if (entry && t < entry.staleUntil) {
+			await kv.set(id, { ...entry, freshUntil: t + BACKOFF_MS, error: error! } satisfies ProductsEntry);
+			return { products: entry.products, ref: entry.ref, tier: entry.tier, source: "stale", error: error! };
+		}
+		await kv.set(id, {
+			key,
+			products: [],
+			ref: "",
+			tier: fallbackTier,
+			fetchedAt: t,
+			freshUntil: t + EMPTY_BACKOFF_MS,
+			staleUntil: t + EMPTY_BACKOFF_MS,
+			error: error!,
+		} satisfies ProductsEntry);
+		return { products: [], ref: "", tier: fallbackTier, source: "empty", error: error! };
+	}
+
+	/** Who the secret key belongs to. `null` without a key. */
+	async function keyInfo(): Promise<KeyInfo | null> {
+		if (!opts.apiKey) return null;
+		const id = `${P_KEY}${hash(opts.apiKey)}`;
+		const cached = await kv.get<KeyEntry>(id);
+		const t = now();
+		if (isRecord(cached) && typeof cached.until === "number" && t < cached.until) return cached.info;
+
+		const res = await request(`${API_BASE}/key`);
+		const owner = res.ok ? parseKeyResponse(res.json) : null;
+		const info: KeyInfo = owner
+			? { ok: true, owner }
+			: { ok: false, error: res.ok ? "Unexpected response from AVDEB" : res.error };
+		await record(info.ok ? null : info.error);
+		await kv.set(id, { info, until: t + (info.ok ? KEY_OK_MS : KEY_FAIL_MS) } satisfies KeyEntry);
+		return info;
+	}
+
+	/** The referral code links carry: the key owner's with a key, else the manual code. */
+	async function ref(): Promise<string> {
+		if (!opts.apiKey) return opts.refCode;
+		const info = await keyInfo();
+		return info?.ok ? info.owner.ref : "";
+	}
+
+	/** "Refresh products now": invalidate every cached query and the key check. */
+	async function flush(): Promise<void> {
+		await kv.set(K_VERSION, (await version()) + 1);
+		for (const { key } of await kv.list(P_KEY)) await kv.delete(key);
+	}
+
+	/** Delete expired and superseded cache entries (daily cron). Returns how many were removed. */
+	async function cleanup(): Promise<number> {
+		const v = await version();
+		const t = now();
+		let removed = 0;
+		for (const { key, value } of await kv.list("cache:")) {
+			const rec = isRecord(value) ? value : {};
+			const expired = key.startsWith(P_PRODUCTS)
+				? !key.startsWith(`${P_PRODUCTS}${v}:`) || !(typeof rec.staleUntil === "number" && t < rec.staleUntil)
+				: !(typeof rec.until === "number" && t < rec.until);
+			if (expired && (await kv.delete(key))) removed++;
+		}
+		return removed;
+	}
+
+	async function stats(): Promise<ClientStats> {
+		const v = await version();
+		const s = await kv.get<StoredStats>(K_STATS);
+		const cached = await kv.list(`${P_PRODUCTS}${v}:`);
+		return {
+			requests: s?.requests ?? 0,
+			errors: s?.errors ?? 0,
+			lastFetchAt: s?.lastFetchAt ?? null,
+			lastError: s?.lastError ?? null,
+			lastErrorAt: s?.lastErrorAt ?? null,
+			cachedQueries: cached.length,
+			cacheVersion: v,
+		};
+	}
+
+	return { products, keyInfo, ref, flush, cleanup, stats };
+}
+
+export type CatalogClient = ReturnType<typeof createCatalogClient>;

package/src/constants.ts

@@ -0,0 +1,53 @@
+/** Shared identifiers and limits. Pure module: no EmDash or Astro imports. */
+
+export const PLUGIN_ID = "avdeb-products";
+export const VERSION = "0.1.0";
+
+export const API_HOST = "api.avdeb.com";
+export const API_BASE = `https://${API_HOST}/v1/catalog`;
+export const SITE_ORIGIN = "https://avdeb.com";
+export const DOCS_URL = "https://avdeb.com/developers/#emdash";
+export const PARTNER_DASHBOARD_URL = "https://avdeb.com/affiliate/dashboard/developers/";
+export const AFFILIATE_URL = "https://avdeb.com/affiliate/";
+
+/** Secret keys are issued as `avdeb_sk_` + 32 letters/digits (partner dashboard → Embeds & API). */
+export const SECRET_KEY_RE = /^avdeb_sk_[A-Za-z0-9]{32}$/;
+export const PUBLISHABLE_KEY_PREFIX = "avdeb_pk_";
+
+/** Catalog API tier limits (api.avdeb.com docs/catalog.md). */
+export const MAX_LIMIT_ANONYMOUS = 12;
+export const MAX_LIMIT_SECRET = 48;
+export const DEFAULT_LIMIT = 6;
+
+export const BLOCK_TYPES = {
+	products: "avdeb-products",
+	product: "avdeb-product",
+	button: "avdeb-button",
+} as const;
+
+export const LAYOUTS = ["grid", "carousel", "list", "spotlight"] as const;
+export type Layout = (typeof LAYOUTS)[number];
+
+export const CARD_STYLES = ["elevated", "outline", "minimal"] as const;
+export type CardStyle = (typeof CARD_STYLES)[number];
+
+export const THEMES = ["inherit", "light", "dark", "auto"] as const;
+export type Theme = (typeof THEMES)[number];
+
+export const IMAGE_RATIOS = ["square", "portrait", "landscape"] as const;
+export type ImageRatio = (typeof IMAGE_RATIOS)[number];
+
+export const PRODUCT_VARIANTS = ["card", "horizontal", "hero"] as const;
+export type ProductVariant = (typeof PRODUCT_VARIANTS)[number];
+
+export const BUTTON_VARIANTS = ["solid", "outline", "link"] as const;
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+
+export const ALIGNMENTS = ["start", "center", "end"] as const;
+export type Alignment = (typeof ALIGNMENTS)[number];
+
+export function oneOf<T extends string>(value: unknown, allowed: readonly T[]): T | undefined {
+	return typeof value === "string" && (allowed as readonly string[]).includes(value)
+		? (value as T)
+		: undefined;
+}

package/src/index.ts

@@ -0,0 +1,125 @@
+/**
+ * AVDEB Products — EmDash plugin.
+ *
+ * Embed AVDEB products (a creator's shop, a category, a search or single products) in Portable Text
+ * content and Astro templates, with the site owner's referral code on every link.
+ *
+ * This is a trusted (native) plugin: it contributes Portable Text block types and Astro render
+ * components, which the sandbox/registry format cannot. It only talks to api.avdeb.com.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { avdebProducts } from "emdash-plugin-avdeb";
+ *
+ * emdash({ plugins: [avdebProducts()] });
+ * ```
+ */
+
+import type { PluginDescriptor, ResolvedPlugin } from "emdash";
+import { definePlugin } from "emdash";
+import { z } from "astro/zod";
+
+import { adminRoute, WIDGET_ID } from "./admin.ts";
+import { portableTextBlocks } from "./blocks.ts";
+import { API_HOST, PLUGIN_ID, VERSION } from "./constants.ts";
+import { cleanupCache, contextRoute, productOptionsRoute, productsRoute, searchRoute } from "./routes.ts";
+import { settingsSchema } from "./settings.ts";
+
+// eslint-disable-next-line typescript/no-empty-object-type -- reserved for future options
+export interface AvdebProductsOptions {}
+
+const capabilities = ["network:request"] as const;
+const allowedHosts = [API_HOST];
+const adminPages = [{ path: "/", label: "AVDEB Products", icon: "storefront" }];
+const adminWidgets = [{ id: WIDGET_ID, title: "AVDEB Products", size: "third" as const }];
+
+/** Descriptor for `emdash({ plugins: [avdebProducts()] })` in astro.config. */
+export function avdebProducts(
+	options: AvdebProductsOptions = {},
+): PluginDescriptor<AvdebProductsOptions> {
+	return {
+		id: PLUGIN_ID,
+		version: VERSION,
+		format: "native",
+		entrypoint: "emdash-plugin-avdeb",
+		componentsEntry: "emdash-plugin-avdeb/astro",
+		options,
+		capabilities: [...capabilities],
+		allowedHosts,
+		adminPages,
+		adminWidgets,
+		settingsSchema,
+		portableTextBlocks,
+	};
+}
+
+const searchInput = z.object({
+	q: z.string().max(100).optional().describe("Search phrase, e.g. 'cat stickers'"),
+	creator: z.string().max(100).optional().describe("Creator slug"),
+	tag: z.string().max(100).optional().describe("Category slug"),
+	type: z.string().max(40).optional().describe("Product type, e.g. 'Sticker'"),
+	limit: z.number().int().min(1).max(48).optional(),
+});
+
+export function createPlugin(_options: AvdebProductsOptions = {}): ResolvedPlugin {
+	return definePlugin({
+		id: PLUGIN_ID,
+		version: VERSION,
+		capabilities: [...capabilities],
+		allowedHosts,
+
+		hooks: {
+			"plugin:activate": {
+				handler: async (_event, ctx) => {
+					await ctx.cron?.schedule("cleanup", { schedule: "@daily" });
+				},
+			},
+			cron: {
+				handler: async (event, ctx) => {
+					if (event.name !== "cleanup") return;
+					const removed = await cleanupCache(ctx);
+					if (removed > 0) ctx.log.info("Removed expired AVDEB cache entries", { removed });
+				},
+			},
+		},
+
+		routes: {
+			// Called in-process by the site renderer (getPublicPluginApiRouteHandler). Returns public
+			// product data only; network calls are cached and capped per minute.
+			products: { public: true, handler: productsRoute },
+			context: { public: true, handler: contextRoute },
+
+			// Editor: the "pick a product" select in the AVDEB Product block.
+			"options/products": { permission: "content:create", handler: productOptionsRoute },
+			"mcp/search": { permission: "content:create", input: searchInput, handler: searchRoute },
+
+			admin: { permission: "plugins:manage", handler: adminRoute },
+		},
+
+		mcp: {
+			tools: {
+				search_avdeb_products: {
+					description:
+						"Search AVDEB products to embed in content. Returns handles plus a ready Portable Text block ({ _type: 'avdeb-product', id }) for each.",
+					route: "mcp/search",
+					input: searchInput,
+					destructive: false,
+				},
+			},
+		},
+
+		admin: {
+			settingsSchema,
+			pages: adminPages,
+			widgets: adminWidgets,
+			portableTextBlocks,
+		},
+	});
+}
+
+export default createPlugin;
+
+export { BLOCK_TYPES, PLUGIN_ID } from "./constants.ts";
+export type { Product, CatalogQuery } from "./catalog.ts";
+export type { DisplaySettings } from "./settings.ts";

package/src/payload.ts

@@ -0,0 +1,78 @@
+/**
+ * Validation of the route payload on the rendering side (defence in depth: everything printed in
+ * HTML is re-checked here, even though the route already normalised it). Pure module.
+ */
+
+import { cleanRef, cleanSlug, isAvdebUrl, sanitizeQuery, type CatalogQuery, type Product } from "./catalog.ts";
+import { MAX_LIMIT_SECRET } from "./constants.ts";
+import { parseDisplay, type DisplaySettings } from "./settings.ts";
+
+export interface EmbedData {
+	products: Product[];
+	ref: string;
+	query: CatalogQuery;
+	display: DisplaySettings;
+}
+
+export interface ContextData {
+	ref: string;
+	display: DisplaySettings;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function num(v: unknown): number | null {
+	return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+}
+
+function text(v: unknown, max: number): string {
+	return typeof v === "string" ? v.trim().slice(0, max) : "";
+}
+
+export function reviveProduct(v: unknown): Product | null {
+	if (!isRecord(v)) return null;
+	const handle = cleanSlug(v.handle);
+	const title = text(v.title, 200);
+	if (!handle || !title || !isAvdebUrl(v.url)) return null;
+	const image = typeof v.image === "string" && v.image.startsWith("https://") ? v.image : null;
+	const currency = typeof v.currency === "string" && /^[A-Z]{3}$/.test(v.currency) ? v.currency : "USD";
+	let creator: Product["creator"] = null;
+	if (isRecord(v.creator) && cleanSlug(v.creator.slug)) {
+		creator = {
+			slug: cleanSlug(v.creator.slug),
+			name: text(v.creator.name, 120) || cleanSlug(v.creator.slug),
+			url: isAvdebUrl(v.creator.url) ? v.creator.url : null,
+		};
+	}
+	const createdAt = typeof v.createdAt === "string" && !Number.isNaN(Date.parse(v.createdAt)) ? v.createdAt : null;
+	return {
+		handle,
+		title,
+		url: v.url,
+		image,
+		price: num(v.price),
+		compareAtPrice: num(v.compareAtPrice),
+		currency,
+		type: text(v.type, 40) || null,
+		tags: Array.isArray(v.tags) ? v.tags.map(cleanSlug).filter(Boolean).slice(0, 20) : [],
+		creator,
+		createdAt,
+	};
+}
+
+export function parseEmbedPayload(data: unknown): EmbedData | null {
+	if (!isRecord(data) || !Array.isArray(data.products)) return null;
+	return {
+		products: data.products.map(reviveProduct).filter((p): p is Product => p !== null),
+		ref: cleanRef(data.ref),
+		query: sanitizeQuery(data.query, MAX_LIMIT_SECRET),
+		display: parseDisplay(data.display),
+	};
+}
+
+export function parseContextPayload(data: unknown): ContextData | null {
+	if (!isRecord(data)) return null;
+	return { ref: cleanRef(data.ref), display: parseDisplay(data.display) };
+}

package/src/routes.ts

@@ -0,0 +1,100 @@
+/**
+ * Plugin route handlers. Only type imports from EmDash, so the handlers run in tests with a fake
+ * context.
+ */
+
+import type { PluginContext, RouteContext } from "emdash";
+
+import { maxLimit, sanitizeQuery, type Product } from "./catalog.ts";
+import { createCatalogClient, type CatalogClient } from "./client.ts";
+import { displayOf, readSettings, type ResolvedSettings, type SettingKey } from "./settings.ts";
+import { formatPrice } from "./view.ts";
+
+type Ctx = Pick<PluginContext, "kv" | "settings" | "http" | "log">;
+
+export async function loadSettings(ctx: Ctx): Promise<ResolvedSettings> {
+	return readSettings((key: SettingKey) => ctx.settings.get(key));
+}
+
+export function clientFor(ctx: Ctx, settings: ResolvedSettings, now?: () => number): CatalogClient {
+	const http = ctx.http;
+	if (!http) throw new Error("AVDEB Products needs the network:request capability for api.avdeb.com");
+	return createCatalogClient({
+		kv: ctx.kv,
+		fetch: (url, init) => http.fetch(url, init),
+		apiKey: settings.apiKey,
+		refCode: settings.refCode,
+		cacheMinutes: settings.cacheMinutes,
+		log: ctx.log,
+		now,
+	});
+}
+
+/** Public: products + presentation settings for the site renderer. Never returns credentials. */
+export async function productsRoute(ctx: RouteContext) {
+	const settings = await loadSettings(ctx);
+	const query = sanitizeQuery(ctx.input, maxLimit(settings.apiKey !== ""));
+	const out = await clientFor(ctx, settings).products(query);
+	return {
+		products: out.products,
+		ref: out.ref,
+		tier: out.tier,
+		query,
+		display: displayOf(settings),
+	};
+}
+
+/** Public: referral code + presentation settings (for buttons and links, no product lookup). */
+export async function contextRoute(ctx: RouteContext) {
+	const settings = await loadSettings(ctx);
+	return { ref: await clientFor(ctx, settings).ref(), display: displayOf(settings) };
+}
+
+function optionLabel(p: Product): string {
+	const price = formatPrice(p.price, p.currency);
+	return price ? `${p.title} · ${price}` : p.title;
+}
+
+/**
+ * Editor: options for the "pick a product" select — the key owner's own products for creators,
+ * otherwise the newest products. Shape required by the editor: `{ items: [{ id, name }] }`.
+ */
+export async function productOptionsRoute(ctx: RouteContext) {
+	const settings = await loadSettings(ctx);
+	const client = clientFor(ctx, settings);
+	const info = await client.keyInfo();
+	const creator = info?.ok ? info.owner.creatorSlug : "";
+	const query = sanitizeQuery(
+		{ creator, limit: maxLimit(settings.apiKey !== "") },
+		maxLimit(settings.apiKey !== ""),
+	);
+	const out = await client.products(query);
+	return { items: out.products.map((p) => ({ id: p.handle, name: optionLabel(p) })) };
+}
+
+/** Editor / MCP: search the catalog and get ready-to-insert block data. */
+export async function searchRoute(ctx: RouteContext) {
+	const settings = await loadSettings(ctx);
+	const query = sanitizeQuery(ctx.input, maxLimit(settings.apiKey !== ""));
+	const out = await clientFor(ctx, settings).products(query);
+	return {
+		products: out.products.map((p) => ({
+			handle: p.handle,
+			title: p.title,
+			price: p.price,
+			currency: p.currency,
+			url: p.url,
+			image: p.image,
+			creator: p.creator?.name ?? null,
+			block: { _type: "avdeb-product", id: p.handle },
+		})),
+		ref: out.ref,
+		...(out.error ? { warning: out.error } : {}),
+	};
+}
+
+/** Daily cron: drop expired cache entries so random public queries can't pile up in KV. */
+export async function cleanupCache(ctx: Ctx): Promise<number> {
+	const settings = await loadSettings(ctx);
+	return clientFor(ctx, settings).cleanup();
+}