emdash-plugin-avdeb 0.1.0

package/src/astro/ProductBlock.astro

@@ -0,0 +1,24 @@
+---
+/** Portable Text renderer for `avdeb-product` blocks (one featured product). */
+import { productRequest } from "../blocks.ts";
+import Embed from "./Embed.astro";
+import { loadEmbed } from "./load.ts";
+
+interface Props {
+	node: Record<string, unknown>;
+}
+
+const req = productRequest(Astro.props.node ?? {});
+const data = req.handle ? await loadEmbed(Astro.locals, Astro.url, { handle: req.handle }) : null;
+---
+
+{
+	data && (
+		<Embed
+			data={data}
+			overrides={req.overrides}
+			viewAll={false}
+			single={{ variant: req.variant, badge: req.badge, note: req.note }}
+		/>
+	)
+}

package/src/astro/ProductsBlock.astro

@@ -0,0 +1,15 @@
+---
+/** Portable Text renderer for `avdeb-products` blocks. */
+import { productsRequest } from "../blocks.ts";
+import Embed from "./Embed.astro";
+import { loadEmbed } from "./load.ts";
+
+interface Props {
+	node: Record<string, unknown>;
+}
+
+const req = productsRequest(Astro.props.node ?? {});
+const data = await loadEmbed(Astro.locals, Astro.url, req.query);
+---
+
+{data && <Embed data={data} overrides={req.overrides} heading={req.heading} intro={req.intro} viewAll={req.viewAll} />}

package/src/astro/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Site-side Portable Text renderers. EmDash merges `blockComponents` into <PortableText>
+ * automatically; a site can still override any type via its own `components.types`.
+ */
+
+import { BLOCK_TYPES } from "../constants.ts";
+import ButtonBlock from "./ButtonBlock.astro";
+import ProductBlock from "./ProductBlock.astro";
+import ProductsBlock from "./ProductsBlock.astro";
+
+export const blockComponents = {
+	[BLOCK_TYPES.products]: ProductsBlock,
+	[BLOCK_TYPES.product]: ProductBlock,
+	[BLOCK_TYPES.button]: ButtonBlock,
+};

package/src/astro/load.ts

@@ -0,0 +1,68 @@
+/**
+ * Server-side data loading for the Astro components. Calls the plugin's public routes in-process
+ * through EmDash's public route dispatcher (no HTTP round-trip), and de-duplicates identical
+ * requests within one page render.
+ */
+
+import { getPublicPluginApiRouteHandler, type PublicPluginRuntimeLocals } from "emdash/plugin-utils";
+
+import { PLUGIN_ID } from "../constants.ts";
+import { parseContextPayload, parseEmbedPayload, type ContextData, type EmbedData } from "../payload.ts";
+
+type Route = "products" | "context";
+
+const perRequest = new WeakMap<object, Map<string, Promise<unknown>>>();
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+async function call(locals: unknown, base: URL, route: Route, body: unknown): Promise<unknown> {
+	const handler = getPublicPluginApiRouteHandler(locals as PublicPluginRuntimeLocals);
+	const request = new Request(new URL(`/_emdash/api/plugins/${PLUGIN_ID}/${route}`, base), {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+	});
+	try {
+		if (handler) {
+			const res = await handler(PLUGIN_ID, "POST", `/${route}`, request);
+			return res.success ? res.data : null;
+		}
+		// No in-process dispatcher (unusual setups): fall back to the public HTTP route.
+		const res = await fetch(request);
+		if (!res.ok) return null;
+		const json: unknown = await res.json();
+		return isRecord(json) ? json.data : null;
+	} catch (error) {
+		console.warn(`[${PLUGIN_ID}] ${route} failed:`, error);
+		return null;
+	}
+}
+
+function memo<T>(locals: unknown, key: string, run: () => Promise<T>): Promise<T> {
+	if (!isRecord(locals)) return run();
+	let map = perRequest.get(locals);
+	if (!map) {
+		map = new Map();
+		perRequest.set(locals, map);
+	}
+	let hit = map.get(key) as Promise<T> | undefined;
+	if (!hit) {
+		hit = run();
+		map.set(key, hit);
+	}
+	return hit;
+}
+
+/** Products for a query (unsanitised; the route validates it). Null when nothing can be shown. */
+export function loadEmbed(locals: unknown, base: URL, query: Record<string, unknown>): Promise<EmbedData | null> {
+	return memo(locals, `p:${JSON.stringify(query)}`, async () =>
+		parseEmbedPayload(await call(locals, base, "products", query)),
+	);
+}
+
+/** Referral code + display settings (buttons). */
+export function loadContext(locals: unknown, base: URL): Promise<ContextData | null> {
+	return memo(locals, "ctx", async () => parseContextPayload(await call(locals, base, "context", {})));
+}

package/src/blocks.ts

@@ -0,0 +1,258 @@
+/**
+ * Portable Text block types (editor slash menu → Block Kit modal) and the mapping from a saved
+ * block node to a catalog request. Pure module.
+ */
+
+import type { PortableTextBlockConfig } from "emdash";
+
+import { cleanSearch, cleanSlug, cleanType, parseAvdebLink } from "./catalog.ts";
+import {
+	ALIGNMENTS,
+	BLOCK_TYPES,
+	BUTTON_VARIANTS,
+	oneOf,
+	PRODUCT_VARIANTS,
+	type Alignment,
+	type ButtonVariant,
+	type ProductVariant,
+} from "./constants.ts";
+import type { DisplayOverrides } from "./view.ts";
+
+const DEFAULT = { label: "Site default", value: "default" };
+
+const layoutOptions = [
+	DEFAULT,
+	{ label: "Grid", value: "grid" },
+	{ label: "Carousel", value: "carousel" },
+	{ label: "List (shop the post)", value: "list" },
+	{ label: "Spotlight (first product featured)", value: "spotlight" },
+];
+const styleOptions = [
+	DEFAULT,
+	{ label: "Elevated", value: "elevated" },
+	{ label: "Outline", value: "outline" },
+	{ label: "Minimal", value: "minimal" },
+];
+const themeOptions = [
+	DEFAULT,
+	{ label: "Inherit from site", value: "inherit" },
+	{ label: "Light", value: "light" },
+	{ label: "Dark", value: "dark" },
+	{ label: "Follow system", value: "auto" },
+];
+
+export const portableTextBlocks: PortableTextBlockConfig[] = [
+	{
+		type: BLOCK_TYPES.products,
+		label: "AVDEB Products",
+		icon: "link-external",
+		category: "Marketing",
+		description: "A grid, carousel or list of AVDEB products with your referral link",
+		fields: [
+			{
+				type: "text_input",
+				action_id: "id",
+				label: "AVDEB link or search",
+				placeholder: "https://avdeb.com/creators/your-slug/ · /category/stickers/ · cat stickers",
+			},
+			{
+				type: "select",
+				action_id: "source",
+				label: "Show",
+				options: [
+					{ label: "Auto-detect from the link or text", value: "auto" },
+					{ label: "A creator's products (slug)", value: "creator" },
+					{ label: "A category (slug)", value: "tag" },
+					{ label: "A product type (e.g. Sticker)", value: "type" },
+					{ label: "Search results", value: "search" },
+					{ label: "Newest products", value: "newest" },
+				],
+				initial_value: "auto",
+			},
+			{ type: "select", action_id: "layout", label: "Layout", options: layoutOptions, initial_value: "default" },
+			{ type: "number_input", action_id: "limit", label: "Number of products (max 12 without a key, 48 with)", min: 1, max: 48, initial_value: 6 },
+			{ type: "number_input", action_id: "columns", label: "Columns (0 = site default)", min: 0, max: 6, initial_value: 0 },
+			{ type: "text_input", action_id: "heading", label: "Heading (optional)", placeholder: "Shop my favourite stickers" },
+			{ type: "text_input", action_id: "intro", label: "Intro text (optional)", multiline: true },
+			{ type: "toggle", action_id: "viewAll", label: "“View all” link to the creator or category page", initial_value: true },
+			{ type: "select", action_id: "cardStyle", label: "Card style", options: styleOptions, initial_value: "default" },
+			{ type: "select", action_id: "theme", label: "Colour theme", options: themeOptions, initial_value: "default" },
+			{ type: "text_input", action_id: "ctaLabel", label: "Button text (optional)", placeholder: "View product" },
+			{ type: "toggle", action_id: "hidePrice", label: "Hide prices", initial_value: false },
+			{ type: "toggle", action_id: "hideCreator", label: "Hide designer names", initial_value: false },
+		],
+	},
+	{
+		type: BLOCK_TYPES.product,
+		label: "AVDEB Product",
+		icon: "link-external",
+		category: "Marketing",
+		description: "Feature one AVDEB product with your own recommendation",
+		fields: [
+			{
+				type: "text_input",
+				action_id: "id",
+				label: "Product link or handle",
+				placeholder: "https://avdeb.com/store/product-handle/",
+			},
+			{
+				type: "select",
+				action_id: "pick",
+				label: "…or pick a recent product",
+				options: [],
+				optionsRoute: "options/products",
+			},
+			{
+				type: "select",
+				action_id: "variant",
+				label: "Style",
+				options: [
+					{ label: "Horizontal card", value: "horizontal" },
+					{ label: "Hero (large)", value: "hero" },
+					{ label: "Compact card", value: "card" },
+				],
+				initial_value: "horizontal",
+			},
+			{ type: "text_input", action_id: "badge", label: "Badge (optional)", placeholder: "Editor's pick" },
+			{ type: "text_input", action_id: "note", label: "Your note (optional)", multiline: true, placeholder: "Why you recommend it" },
+			{ type: "text_input", action_id: "ctaLabel", label: "Button text (optional)", placeholder: "View product" },
+			{ type: "select", action_id: "cardStyle", label: "Card style", options: styleOptions, initial_value: "default" },
+			{ type: "select", action_id: "theme", label: "Colour theme", options: themeOptions, initial_value: "default" },
+		],
+	},
+	{
+		type: BLOCK_TYPES.button,
+		label: "AVDEB Button",
+		icon: "link",
+		category: "Marketing",
+		description: "A call-to-action button to any AVDEB page, with your referral code",
+		fields: [
+			{ type: "text_input", action_id: "id", label: "AVDEB link", placeholder: "https://avdeb.com/creators/your-slug/" },
+			{ type: "text_input", action_id: "label", label: "Button text", initial_value: "Shop on AVDEB" },
+			{
+				type: "select",
+				action_id: "variant",
+				label: "Style",
+				options: [
+					{ label: "Solid", value: "solid" },
+					{ label: "Outline", value: "outline" },
+					{ label: "Text link with arrow", value: "link" },
+				],
+				initial_value: "solid",
+			},
+			{
+				type: "select",
+				action_id: "align",
+				label: "Alignment",
+				options: [
+					{ label: "Start", value: "start" },
+					{ label: "Center", value: "center" },
+					{ label: "End", value: "end" },
+				],
+				initial_value: "start",
+			},
+		],
+	},
+];
+
+type Node = Record<string, unknown>;
+
+function s(v: unknown): string {
+	return typeof v === "string" ? v.trim() : "";
+}
+
+function overridesOf(node: Node): DisplayOverrides {
+	const pick = (v: unknown) => (v === "default" || v === "" ? undefined : v);
+	return {
+		layout: pick(node.layout),
+		columns: node.columns,
+		cardStyle: pick(node.cardStyle),
+		theme: pick(node.theme),
+		ctaLabel: node.ctaLabel,
+		hidePrice: node.hidePrice,
+		hideCreator: node.hideCreator,
+	};
+}
+
+export interface ProductsRequest {
+	/** Unsanitised query for the route (it re-validates and clamps to the tier max). */
+	query: Record<string, unknown>;
+	overrides: DisplayOverrides;
+	heading: string;
+	intro: string;
+	viewAll: boolean;
+}
+
+/** `avdeb-products` node → catalog request. */
+export function productsRequest(node: Node): ProductsRequest {
+	const raw = s(node.id);
+	const source = s(node.source) || "auto";
+	const link = parseAvdebLink(raw);
+	const query: Record<string, unknown> = { limit: node.limit };
+	const slug = (kind: "creator" | "tag") => (link?.kind === kind ? link.value : cleanSlug(raw));
+
+	switch (source) {
+		case "creator":
+			query.creator = slug("creator");
+			break;
+		case "tag":
+			query.tag = slug("tag");
+			break;
+		case "type":
+			query.type = cleanType(raw);
+			break;
+		case "search":
+			query.q = cleanSearch(raw);
+			break;
+		case "newest":
+			break;
+		default:
+			if (link) query[link.kind] = link.value;
+			else if (raw) query.q = cleanSearch(raw);
+	}
+	return {
+		query,
+		overrides: overridesOf(node),
+		heading: s(node.heading).slice(0, 120),
+		intro: s(node.intro).slice(0, 400),
+		viewAll: node.viewAll !== false,
+	};
+}
+
+export interface ProductRequest {
+	handle: string;
+	variant: ProductVariant;
+	badge: string;
+	note: string;
+	overrides: DisplayOverrides;
+}
+
+/** `avdeb-product` node → one product. A link/handle in `id` wins over the picker. */
+export function productRequest(node: Node): ProductRequest {
+	const raw = s(node.id);
+	const link = parseAvdebLink(raw);
+	const fromId = link ? (link.kind === "handle" ? link.value : "") : /[/.:]/.test(raw) ? "" : cleanSlug(raw);
+	return {
+		handle: fromId || cleanSlug(node.pick),
+		variant: oneOf(node.variant, PRODUCT_VARIANTS) ?? "horizontal",
+		badge: s(node.badge).slice(0, 40),
+		note: s(node.note).slice(0, 600),
+		overrides: overridesOf(node),
+	};
+}
+
+export interface ButtonRequest {
+	href: string;
+	label: string;
+	variant: ButtonVariant;
+	align: Alignment;
+}
+
+export function buttonRequest(node: Node): ButtonRequest {
+	return {
+		href: s(node.id) || "/",
+		label: s(node.label).slice(0, 80) || "Shop on AVDEB",
+		variant: oneOf(node.variant, BUTTON_VARIANTS) ?? "solid",
+		align: oneOf(node.align, ALIGNMENTS) ?? "start",
+	};
+}

package/src/catalog.ts

@@ -0,0 +1,292 @@
+/**
+ * AVDEB catalog API contract: query sanitising, response validation, link helpers.
+ * Pure module — safe to import from routes, Astro components and tests.
+ */
+
+import {
+	API_BASE,
+	DEFAULT_LIMIT,
+	MAX_LIMIT_ANONYMOUS,
+	MAX_LIMIT_SECRET,
+	PUBLISHABLE_KEY_PREFIX,
+	SECRET_KEY_RE,
+	SITE_ORIGIN,
+} from "./constants.ts";
+
+export interface CatalogQuery {
+	creator?: string;
+	tag?: string;
+	type?: string;
+	handle?: string;
+	q?: string;
+	limit: number;
+}
+
+export interface ProductCreator {
+	slug: string;
+	name: string;
+	url: string | null;
+}
+
+export interface Product {
+	handle: string;
+	title: string;
+	url: string;
+	image: string | null;
+	price: number | null;
+	compareAtPrice: number | null;
+	currency: string;
+	type: string | null;
+	tags: string[];
+	creator: ProductCreator | null;
+	createdAt: string | null;
+}
+
+export type Tier = "anonymous" | "publishable" | "secret";
+
+export interface ProductsResult {
+	products: Product[];
+	ref: string;
+	tier: Tier;
+}
+
+export interface KeyOwner {
+	type: string;
+	name: string;
+	ref: string;
+	creatorSlug: string;
+}
+
+export type KeyProblem = "publishable" | "malformed";
+
+const SLUG_RE = /[^a-z0-9-]+/g;
+const TYPE_RE = /[^\p{L}\p{N} &'-]+/gu;
+// eslint-disable-next-line no-control-regex -- strip control characters from search input
+const CONTROL_RE = /[\u0000-\u001f\u007f]+/g;
+const CURRENCY_RE = /^[A-Z]{3}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function str(value: unknown): string {
+	return typeof value === "string" ? value : typeof value === "number" ? String(value) : "";
+}
+
+/** Referral codes are letters, digits, "-" and "_" (as issued in the AVDEB affiliate dashboard). */
+export function cleanRef(code: unknown): string {
+	return str(code).replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40);
+}
+
+/** Lower-case URL slug (creator, category, product handle). */
+export function cleanSlug(value: unknown): string {
+	return str(value).trim().toLowerCase().replace(SLUG_RE, "-").replace(/^-+|-+$/g, "").slice(0, 100);
+}
+
+/** Product type such as "Sticker" or "Phone Case". */
+export function cleanType(value: unknown): string {
+	return str(value).replace(TYPE_RE, "").replace(/\s+/g, " ").trim().slice(0, 40);
+}
+
+/** Free-text search phrase. */
+export function cleanSearch(value: unknown): string {
+	return str(value).replace(CONTROL_RE, " ").replace(/\s+/g, " ").trim().slice(0, 100);
+}
+
+/** `null` for a usable secret key, otherwise why it can't be used. Empty input is not a problem. */
+export function keyProblem(key: unknown): KeyProblem | null {
+	const k = str(key).trim();
+	if (k === "" || SECRET_KEY_RE.test(k)) return null;
+	return k.startsWith(PUBLISHABLE_KEY_PREFIX) ? "publishable" : "malformed";
+}
+
+/** The key when it is a well-formed secret key, otherwise "". */
+export function usableKey(key: unknown): string {
+	const k = str(key).trim();
+	return SECRET_KEY_RE.test(k) ? k : "";
+}
+
+export function maxLimit(hasKey: boolean): number {
+	return hasKey ? MAX_LIMIT_SECRET : MAX_LIMIT_ANONYMOUS;
+}
+
+export function isAvdebUrl(url: unknown): url is string {
+	if (typeof url !== "string") return false;
+	try {
+		const u = new URL(url);
+		const host = u.hostname.toLowerCase();
+		return u.protocol === "https:" && (host === "avdeb.com" || host === "www.avdeb.com");
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Absolute avdeb.com URL for an avdeb.com URL or a site path ("/store/cat/"), with `ref` set when
+ * given. Anything pointing elsewhere returns "" so callers never link off-site by accident.
+ */
+export function avdebLink(input: unknown, ref = ""): string {
+	let raw = str(input).trim();
+	if (raw === "") return "";
+	if (raw.startsWith("/") && !raw.startsWith("//")) raw = SITE_ORIGIN + raw;
+	else if (/^(www\.)?avdeb\.com(\/|$)/i.test(raw)) raw = "https://" + raw;
+	if (!isAvdebUrl(raw)) return "";
+	const u = new URL(raw);
+	const code = cleanRef(ref);
+	if (code !== "") u.searchParams.set("ref", code);
+	return u.toString();
+}
+
+export function hasRef(url: string): boolean {
+	try {
+		return new URL(url).searchParams.has("ref");
+	} catch {
+		return false;
+	}
+}
+
+export type LinkTarget = { kind: "creator" | "tag" | "handle"; value: string };
+
+/**
+ * Recognise an AVDEB page a user pasted: /creators/{slug}/, /category/{slug}/, /store/{handle}/.
+ * Accepts full URLs, scheme-less "avdeb.com/…" and bare paths.
+ */
+export function parseAvdebLink(input: unknown): LinkTarget | null {
+	const raw = str(input).trim();
+	if (raw === "") return null;
+	let path: string;
+	if (raw.startsWith("/") && !raw.startsWith("//")) {
+		path = raw;
+	} else {
+		const withScheme = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+		try {
+			const u = new URL(withScheme);
+			const host = u.hostname.toLowerCase();
+			if (host !== "avdeb.com" && host !== "www.avdeb.com") return null;
+			path = u.pathname;
+		} catch {
+			return null;
+		}
+	}
+	const [section, slug] = path.split(/[?#]/)[0]!.split("/").filter(Boolean);
+	const value = cleanSlug(slug);
+	if (!section || value === "") return null;
+	const kind = ({ creators: "creator", category: "tag", store: "handle" } as const)[
+		section.toLowerCase() as "creators" | "category" | "store"
+	];
+	return kind ? { kind, value } : null;
+}
+
+/**
+ * Validate an untrusted query (route input). Unknown keys are ignored; an empty filter set means
+ * "newest products". `limit` is clamped to the tier max; a handle always means one product.
+ */
+export function sanitizeQuery(input: unknown, max: number): CatalogQuery {
+	const src = isRecord(input) ? input : {};
+	const query: CatalogQuery = { limit: DEFAULT_LIMIT };
+	const creator = cleanSlug(src.creator);
+	const tag = cleanSlug(src.tag);
+	const type = cleanType(src.type);
+	const handle = cleanSlug(src.handle);
+	const q = cleanSearch(src.q);
+	if (creator) query.creator = creator;
+	if (tag) query.tag = tag;
+	if (type) query.type = type;
+	if (handle) query.handle = handle;
+	if (q) query.q = q;
+	const limit = Math.trunc(Number(src.limit));
+	query.limit = handle ? 1 : Number.isFinite(limit) && limit > 0 ? Math.min(max, limit) : Math.min(max, DEFAULT_LIMIT);
+	return query;
+}
+
+/** Stable string for a query (cache key, request de-duplication). */
+export function queryKey(q: CatalogQuery): string {
+	return [q.creator ?? "", q.tag ?? "", q.type ?? "", q.handle ?? "", q.q ?? "", q.limit].join("|");
+}
+
+/** GET /v1/catalog/products URL. `ref` is only sent without a key (key holders get their own code). */
+export function productsUrl(q: CatalogQuery, ref = ""): string {
+	const params = new URLSearchParams();
+	for (const k of ["creator", "tag", "type", "handle", "q"] as const) {
+		const v = q[k];
+		if (v) params.set(k, v);
+	}
+	params.set("limit", String(q.limit));
+	const code = cleanRef(ref);
+	if (code) params.set("ref", code);
+	return `${API_BASE}/products?${params.toString()}`;
+}
+
+function money(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/** Keep only fields the plugin renders, validated. `null` for anything unusable. */
+export function normalizeProduct(raw: unknown): Product | null {
+	if (!isRecord(raw)) return null;
+	const handle = cleanSlug(raw.handle);
+	const title = str(raw.title).replace(CONTROL_RE, " ").trim().slice(0, 200);
+	const url = str(raw.url);
+	if (!handle || !title || !isAvdebUrl(url)) return null;
+
+	const image = str(raw.image);
+	const currency = str(raw.currency).toUpperCase();
+	let creator: ProductCreator | null = null;
+	if (isRecord(raw.creator)) {
+		const slug = cleanSlug(raw.creator.slug);
+		if (slug) {
+			const creatorUrl = str(raw.creator.url);
+			creator = {
+				slug,
+				name: str(raw.creator.name).trim().slice(0, 120) || slug,
+				url: isAvdebUrl(creatorUrl) ? creatorUrl : null,
+			};
+		}
+	}
+	const createdAt = str(raw.created_at);
+	return {
+		handle,
+		title,
+		url,
+		image: image.startsWith("https://") ? image : null,
+		price: money(raw.price),
+		compareAtPrice: money(raw.compare_at_price),
+		currency: CURRENCY_RE.test(currency) ? currency : "USD",
+		type: cleanType(raw.type) || null,
+		tags: Array.isArray(raw.tags) ? raw.tags.map(cleanSlug).filter(Boolean).slice(0, 20) : [],
+		creator,
+		createdAt: createdAt && !Number.isNaN(Date.parse(createdAt)) ? createdAt : null,
+	};
+}
+
+export function parseProductsResponse(json: unknown): ProductsResult | null {
+	if (!isRecord(json) || !Array.isArray(json.products)) return null;
+	const products: Product[] = [];
+	const seen = new Set<string>();
+	for (const raw of json.products) {
+		const p = normalizeProduct(raw);
+		if (p && !seen.has(p.handle)) {
+			seen.add(p.handle);
+			products.push(p);
+		}
+	}
+	const tier = json.tier === "secret" || json.tier === "publishable" ? json.tier : "anonymous";
+	return { products, ref: cleanRef(json.ref), tier };
+}
+
+export function parseKeyResponse(json: unknown): KeyOwner | null {
+	if (!isRecord(json) || !isRecord(json.owner)) return null;
+	const o = json.owner;
+	return {
+		type: str(o.type).replace(/[^a-z_-]/gi, "").toLowerCase().slice(0, 20),
+		name: str(o.name).trim().slice(0, 120),
+		ref: cleanRef(o.ref),
+		creatorSlug: cleanSlug(o.creator_slug),
+	};
+}
+
+/** Error message from an API error body (`{ "error": "…" }`) or the HTTP status. */
+export function apiErrorMessage(status: number, json: unknown): string {
+	const msg = isRecord(json) ? str(json.error).trim().slice(0, 200) : "";
+	return msg || `HTTP ${status}`;
+}