emdash-plugin-avdeb 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+- First release: AVDEB Products / AVDEB Product / AVDEB Button Portable Text blocks; grid, carousel, list
+  and spotlight layouts; horizontal, hero and compact single-product styles; template components
+  (`emdash-plugin-avdeb/ui`); settings with encrypted secret key; KV cache with stale fallback, request
+  budget and daily cleanup; Block Kit overview page and dashboard widget; `search_avdeb_products` MCP tool.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AVDEB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# AVDEB Products for EmDash
+
+Embed [AVDEB](https://avdeb.com/developers/#emdash) products in an [EmDash](https://github.com/emdash-cms/emdash) site — a creator's shop, a category, a search or a single product — with **your referral code on every link**.
+
+- **Three editor blocks** — type `/` in any rich-text field: **AVDEB Products**, **AVDEB Product**, **AVDEB Button**. Paste a creator, category or product link and the source is detected automatically.
+- **Four layouts** — grid, carousel (scroll-snap, keyboard + arrow buttons), list ("shop the post") and spotlight (first product featured). Single products as compact card, horizontal card or hero, with your own badge and note.
+- **Looks native on any theme** — container queries (embeds adapt to the column they sit in, not the viewport), inherit / light / dark / system themes, three card styles, accent colour, corner radius, image shape. Every selector is `:where()`-wrapped, so your CSS always wins.
+- **Fast and resilient** — products are fetched server-side, cached in plugin KV per query, and the last good copy is served for a week if AVDEB is unreachable. Identical embeds on one page share a single lookup.
+- **Honest links** — referral links get `rel="sponsored"`; an optional disclosure line appears under embeds that carry a code.
+- **Private by default** — no third-party scripts, no cookies, no iframes, no tracking. The only client JS is ~40 lines for carousel arrows.
+- **Admin overview** — connection status ("Connected as …"), cache stats, a live product preview, "Refresh products now", plus a dashboard widget.
+- **Agent-ready** — an MCP tool (`search_avdeb_products`) returns products with ready-to-insert block data.
+
+## Install
+
+```sh
+npm install emdash-plugin-avdeb
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import emdash from "emdash/astro";
+import { avdebProducts } from "emdash-plugin-avdeb";
+
+export default defineConfig({
+	integrations: [
+		emdash({
+			// …database, storage…
+			plugins: [avdebProducts()],
+		}),
+	],
+});
+```
+
+Requires EmDash ≥ 1.1 and Astro ≥ 6. This is a **trusted (native) plugin**: it adds Portable Text block types and Astro render components, which the sandboxed registry format can't. It requests one capability, `network:request`, limited to `api.avdeb.com`.
+
+## Configure
+
+Open **Plugins → AVDEB Products → Settings** in the EmDash admin.
+
+| Setting | |
+|---|---|
+| **Secret key** | Optional, recommended. `avdeb_sk_…` from the partner dashboard → *Embeds & API*. Your referral code is added automatically and embeds can show up to 48 products. Stored encrypted — the site needs `EMDASH_ENCRYPTION_KEY`. |
+| **Referral code** | Used only without a key: added as `?ref=` to every AVDEB link (max 12 products per embed). |
+| Layout, columns, card style, theme, accent colour, radius, image shape, button text | Site-wide defaults; every block can override them. |
+| Prices / designer names / Sale & New badges / new tab | Toggles. |
+| Disclosure | Shown under embeds whose links carry a referral code (e.g. US FTC rules). |
+| Refresh every | Cache lifetime in minutes (default 360). |
+
+Without a key or code the plugin still works and shows plain AVDEB links.
+
+## Become an AVDEB affiliate (or creator)
+
+You only need an account to earn commission. Program details:
+[avdeb.com/affiliate](https://avdeb.com/affiliate/) — 5% commission, 30-day cookie, monthly PayPal payouts in USD
+($50 minimum), open worldwide, approval usually within 24 hours.
+
+1. Open [avdeb.com/affiliate/apply](https://avdeb.com/affiliate/apply/).
+2. **Account** — email + password (or *Sign in* if you already have an AVDEB account).
+3. **Program** — *Affiliate* (share products, earn commission), *Creator* (submit sticker / 3D designs that
+   AVDEB prints and ships; you earn on every sale), or both.
+4. **Personal information & details** — first/last name, country, tax residency, legal name (business name optional).
+5. **Address** — street, city, state/province, postal code.
+6. **Payout & promotion** — PayPal email for commissions; optionally your website and social links.
+7. Accept the Terms & Conditions and Privacy Policy → **Create Account & Apply**.
+8. After approval you get your referral link by email and in the dashboard.
+9. Partner dashboard → **Embeds & API** ([direct link](https://avdeb.com/affiliate/dashboard/developers/)) →
+   create a **secret key** (`avdeb_sk_…`), or copy your referral code from **Links**.
+10. EmDash admin → **Plugins → AVDEB Products → Settings** → paste the key (or code) → **Save**. The overview
+    shows "Connected as …" and every embed now carries your code. (A key needs `EMDASH_ENCRYPTION_KEY` set on the site.)
+
+Creators: once your designs are listed, show them with `<AvdebProducts creator="your-slug" />` or an
+**AVDEB Products** block pointed at `https://avdeb.com/creators/your-slug/`.
+
+Please disclose affiliate links to your readers — turn on the **Disclosure** setting and it's added for you.
+
+## In content
+
+| Block | Fields |
+|---|---|
+| **AVDEB Products** | Link or search (`https://avdeb.com/creators/you/`, `/category/stickers/`, `cat stickers`), source (auto, creator, category, product type, search, newest), layout, number, columns, heading, intro, "View all" link, card style, theme, button text, hide prices / designers |
+| **AVDEB Product** | Product link or handle — or pick one of your recent products — style (horizontal, hero, compact), badge ("Editor's pick"), your note, button text |
+| **AVDEB Button** | Any AVDEB link, text, style (solid, outline, text link), alignment |
+
+Renderers are wired into `<PortableText>` automatically. Override one with your own component via `components.types["avdeb-products"]`.
+
+## In templates
+
+```astro
+---
+import { AvdebProducts, AvdebProduct, AvdebButton } from "emdash-plugin-avdeb/ui";
+---
+
+<AvdebProducts creator="your-slug" layout="carousel" limit={8} heading="From my shop" />
+<AvdebProducts url="https://avdeb.com/category/stickers/" columns={4} cardStyle="outline" />
+<AvdebProducts q="cat stickers" layout="list" limit={3} headingLevel={3} heading="In this post" />
+<AvdebProduct handle="cat-sticker" variant="hero" badge="Editor's pick" note="I use it every day." />
+<AvdebButton href="/creators/your-slug/" label="Visit my shop" variant="outline" align="center" />
+```
+
+`AvdebProducts` accepts `url | creator | tag | type | q`, `limit`, `layout`, `columns`, `cardStyle`, `theme`, `heading`, `intro`, `headingLevel`, `viewAll`, `ctaLabel`, `hidePrice`, `hideCreator`, `class`.
+
+## Theming
+
+Everything is a CSS custom property on `.avdeb` (embeds) or `.avdeb-cta` (buttons):
+
+```css
+.avdeb {
+	--avdeb-accent: #4d7f5a;          /* prices, sale badge, CTAs, focus ring */
+	--avdeb-accent-contrast: #fff;    /* text on accent */
+	--avdeb-radius: 20px;
+	--avdeb-gap: 1.25rem;
+	--avdeb-card-bg: #fff;
+	--avdeb-border: #e5e7eb;
+	--avdeb-shadow: 0 12px 32px -16px rgb(0 0 0 / 0.3);
+	--avdeb-font-title: "Fraunces", serif;
+}
+.avdeb[data-theme="dark"] { --avdeb-card-bg: #111; }
+```
+
+Also available: `--avdeb-surface`, `--avdeb-border-soft`, `--avdeb-media-bg`, `--avdeb-muted`, `--avdeb-badge-bg`, `--avdeb-badge-text`, `--avdeb-shadow-hover`, `--avdeb-pad`, `--avdeb-ratio`. BEM classes (`.avdeb-card__title`, `.avdeb-badge--sale`, …) are stable.
+
+## How it works
+
+```mermaid
+sequenceDiagram
+    participant Page as Astro page
+    participant Route as Plugin route (in-process)
+    participant KV as Plugin KV
+    participant API as api.avdeb.com
+    Page->>Route: products { creator, limit }
+    Route->>KV: cached for this query?
+    alt fresh
+        KV-->>Route: products
+    else missing or stale
+        Route->>API: GET /v1/catalog/products (Bearer avdeb_sk_…)
+        API-->>Route: products + ref
+        Route->>KV: store (fresh N min, last good copy 7 days)
+    end
+    Route-->>Page: products + display settings (never the key)
+    Page->>Page: render cards (HTML + CSS)
+```
+
+The render route is public (EmDash's SSR dispatcher only calls public routes), so it returns only public catalog data, re-validates every input, caps AVDEB requests at 30 per minute and a daily cron removes expired cache entries. The secret key never leaves the server.
+
+## Development
+
+```sh
+npm install
+npm test            # node --test (Node ≥ 22.18, TypeScript type-stripping, no build step)
+npm run typecheck
+```
+
+```
+src/index.ts        descriptor (astro.config) + createPlugin(): capabilities, routes, cron, MCP, admin
+src/catalog.ts      catalog API contract: query sanitising, response validation, links
+src/client.ts       KV cache: fresh / stale / back-off, request budget, key check, cleanup
+src/settings.ts     settings schema + validation
+src/blocks.ts       Portable Text block definitions, block node → request
+src/view.ts         card view models, prices, badges, "View all", inline style
+src/routes.ts       route handlers          src/admin.ts   Block Kit overview + widget
+src/payload.ts      re-validation on the rendering side
+src/astro/          Embed.astro (all layouts + styles), Button.astro, block renderers, loader
+src/ui.ts           template components
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "emdash-plugin-avdeb",
+	"version": "0.1.0",
+	"description": "Embed AVDEB products in EmDash CMS — grid, carousel, list and spotlight blocks with your affiliate or creator referral link",
+	"type": "module",
+	"main": "src/index.ts",
+	"exports": {
+		".": "./src/index.ts",
+		"./astro": "./src/astro/index.ts",
+		"./ui": "./src/ui.ts"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"keywords": [
+		"emdash",
+		"emdash-plugin",
+		"cms",
+		"astro",
+		"portable-text",
+		"affiliate",
+		"product-embed",
+		"avdeb"
+	],
+	"homepage": "https://avdeb.com/developers/#emdash",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Avdebcom/emdash-plugin-avdeb.git"
+	},
+	"bugs": {
+		"url": "https://github.com/Avdebcom/emdash-plugin-avdeb/issues"
+	},
+	"author": {
+		"name": "AVDEB",
+		"url": "https://avdeb.com/developers/"
+	},
+	"license": "MIT",
+	"sideEffects": false,
+	"peerDependencies": {
+		"astro": ">=6.0.0",
+		"emdash": ">=1.1.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.18.0",
+		"astro": "^6.0.0",
+		"emdash": "^1.1.0",
+		"typescript": "^5.9.0"
+	},
+	"scripts": {
+		"test": "node --test \"tests/**/*.test.ts\"",
+		"typecheck": "tsc --noEmit"
+	}
+}

package/src/admin.ts

@@ -0,0 +1,273 @@
+/**
+ * Block Kit admin: the "AVDEB Products" overview page and the dashboard widget.
+ * The settings form itself is generated by EmDash from `settingsSchema`.
+ */
+
+import type { RouteContext } from "emdash";
+
+import { keyProblem, maxLimit } from "./catalog.ts";
+import type { CatalogClient, ClientStats, KeyInfo } from "./client.ts";
+import { AFFILIATE_URL, DOCS_URL, PARTNER_DASHBOARD_URL } from "./constants.ts";
+import { clientFor, loadSettings } from "./routes.ts";
+import type { ResolvedSettings } from "./settings.ts";
+import { formatPrice } from "./view.ts";
+
+type Block = Record<string, unknown>;
+export interface BlockResult {
+	blocks: Block[];
+	toast?: { message: string; type: "success" | "error" | "info" };
+}
+
+export const WIDGET_ID = "status";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** "3 min ago" style relative time. */
+export function ago(then: number | null, now: number): string {
+	if (!then) return "never";
+	const s = Math.max(0, Math.round((now - then) / 1000));
+	if (s < 60) return "just now";
+	const m = Math.round(s / 60);
+	if (m < 60) return `${m} min ago`;
+	const h = Math.round(m / 60);
+	if (h < 48) return `${h} h ago`;
+	return `${Math.round(h / 24)} days ago`;
+}
+
+/** Connection status as a banner (or null when everything is fine). */
+export function connectionBanner(settings: ResolvedSettings, info: KeyInfo | null): Block | null {
+	const problem = keyProblem(settings.rawApiKey);
+	if (problem === "publishable") {
+		return {
+			type: "banner",
+			variant: "error",
+			title: "That is a publishable key",
+			description:
+				"Publishable keys (avdeb_pk_…) are for the browser embed. This plugin calls AVDEB from your server and needs a secret key that starts with avdeb_sk_.",
+		};
+	}
+	if (problem === "malformed") {
+		return {
+			type: "banner",
+			variant: "error",
+			title: "The saved key doesn't look like an AVDEB secret key",
+			description: "Expected avdeb_sk_ followed by 32 letters and digits. Products still show, without your key.",
+		};
+	}
+	if (info && !info.ok) {
+		return {
+			type: "banner",
+			variant: "error",
+			title: "AVDEB did not accept the secret key",
+			description: `${info.error}. Check the key in the partner dashboard, or remove it to use a referral code instead.`,
+		};
+	}
+	if (info?.ok && !info.owner.ref) {
+		return {
+			type: "banner",
+			variant: "alert",
+			title: "Connected, but your account has no referral code yet",
+			description: "Links work but aren't credited to you. Creators get the code of their linked affiliate account.",
+		};
+	}
+	if (!settings.apiKey && !settings.refCode) {
+		return {
+			type: "banner",
+			variant: "alert",
+			title: "Links aren't credited to you yet",
+			description:
+				"Add a secret key (recommended) or your referral code in Settings. Without either, embeds show plain AVDEB links.",
+		};
+	}
+	return null;
+}
+
+function connectionFields(settings: ResolvedSettings, info: KeyInfo | null): Block {
+	const fields: Array<{ label: string; value: string }> = [];
+	if (info?.ok) {
+		fields.push({ label: "Connected as", value: `${info.owner.name || "AVDEB partner"} (${info.owner.type || "partner"})` });
+		fields.push({ label: "Referral code", value: info.owner.ref || "—" });
+	} else {
+		fields.push({ label: "Connection", value: settings.apiKey ? "Secret key (not verified)" : "No key — public catalog" });
+		fields.push({ label: "Referral code", value: settings.refCode || "—" });
+	}
+	fields.push({ label: "Products per embed", value: `up to ${maxLimit(settings.apiKey !== "" && info?.ok === true)}` });
+	fields.push({ label: "Cache", value: `${settings.cacheMinutes} min, last good copy kept 7 days` });
+	return { type: "fields", fields };
+}
+
+function statsBlock(stats: ClientStats, now: number): Block {
+	return {
+		type: "stats",
+		items: [
+			{ label: "Cached embeds", value: stats.cachedQueries, description: "distinct queries" },
+			{ label: "AVDEB requests", value: stats.requests, description: `last ${ago(stats.lastFetchAt, now)}` },
+			{
+				label: "Errors",
+				value: stats.errors,
+				description: stats.lastError ? `${stats.lastError} (${ago(stats.lastErrorAt, now)})` : "none",
+			},
+		],
+	};
+}
+
+function actions(compact: boolean): Block {
+	const elements: Block[] = [
+		{ type: "button", action_id: "refresh_cache", label: "Refresh products now", style: "primary" },
+	];
+	if (!compact) elements.push({ type: "button", action_id: "test_connection", label: "Test connection" });
+	elements.push({ type: "link", label: "Settings", target: { kind: "plugin-settings" }, appearance: "secondary" });
+	if (!compact) {
+		elements.push({ type: "link", label: "Get a secret key", target: { kind: "external", url: PARTNER_DASHBOARD_URL } });
+		elements.push({ type: "link", label: "Become an affiliate", target: { kind: "external", url: AFFILIATE_URL } });
+	}
+	return { type: "actions", elements };
+}
+
+const TEMPLATE_SNIPPET = `---
+import { AvdebProducts, AvdebProduct, AvdebButton } from "emdash-plugin-avdeb/ui";
+---
+
+<AvdebProducts creator="your-slug" layout="carousel" limit={8} heading="From my shop" />
+<AvdebProducts tag="stickers" layout="grid" columns={4} cardStyle="outline" />
+<AvdebProducts q="cat stickers" layout="list" limit={3} />
+<AvdebProduct handle="cat-sticker" variant="hero" badge="Editor's pick" note="I use it every day." />
+<AvdebButton href="/creators/your-slug/" label="Visit my shop" variant="outline" />`;
+
+const CSS_SNIPPET = `/* Every value is a CSS custom property; selectors use :where(), so yours always win. */
+.avdeb {
+  --avdeb-accent: #4d7f5a;      /* prices, badges, buttons */
+  --avdeb-radius: 20px;
+  --avdeb-gap: 1.25rem;
+  --avdeb-card-bg: #fff;
+  --avdeb-font-title: "Fraunces", serif;
+}`;
+
+function usage(): Block[] {
+	return [
+		{
+			type: "accordion",
+			label: "Add products to a post",
+			default_open: false,
+			blocks: [
+				{
+					type: "context",
+					text: "In any rich-text field type “/” and choose AVDEB Products, AVDEB Product or AVDEB Button. Paste a creator, category or product link — the source is detected automatically.",
+				},
+			],
+		},
+		{
+			type: "accordion",
+			label: "Use in Astro templates",
+			default_open: false,
+			blocks: [{ type: "code", language: "tsx", code: TEMPLATE_SNIPPET }],
+		},
+		{
+			type: "accordion",
+			label: "Match your theme",
+			default_open: false,
+			blocks: [{ type: "code", language: "css", code: CSS_SNIPPET }],
+		},
+		{ type: "actions", elements: [{ type: "link", label: "Documentation", target: { kind: "external", url: DOCS_URL } }] },
+	];
+}
+
+async function previewTable(client: CatalogClient, settings: ResolvedSettings, info: KeyInfo | null): Promise<Block[]> {
+	const creator = info?.ok ? info.owner.creatorSlug : "";
+	const out = await client.products({ ...(creator ? { creator } : {}), limit: 6 });
+	return [
+		{ type: "header", text: creator ? "Your newest products" : "Newest on AVDEB" },
+		{
+			type: "table",
+			page_action_id: "preview_page",
+			columns: [
+				{ key: "title", label: "Product" },
+				{ key: "price", label: "Price" },
+				{ key: "creator", label: "Designer" },
+				{ key: "handle", label: "Handle", format: "code" },
+			],
+			rows: out.products.map((p) => ({
+				title: p.title,
+				price: formatPrice(p.price, p.currency) ?? "—",
+				creator: p.creator?.name ?? "—",
+				handle: p.handle,
+			})),
+			empty_text: out.error ? `AVDEB could not be reached: ${out.error}` : "No products found.",
+		},
+		{
+			type: "context",
+			text: settings.refCode || info?.ok ? "Every product link on your site carries your referral code and rel=\"sponsored\"." : "Links are plain until you add a key or referral code.",
+		},
+	];
+}
+
+export async function overviewPage(ctx: RouteContext, now = Date.now()): Promise<Block[]> {
+	const settings = await loadSettings(ctx);
+	const client = clientFor(ctx, settings);
+	const info = await client.keyInfo();
+	const banner = connectionBanner(settings, info);
+	return [
+		{ type: "header", text: "AVDEB Products" },
+		{
+			type: "context",
+			text: "Embed AVDEB products — a creator's shop, a category, a search or single products — with your referral code on every link.",
+		},
+		...(banner ? [banner] : []),
+		connectionFields(settings, info),
+		statsBlock(await client.stats(), now),
+		actions(false),
+		{ type: "divider" },
+		...(await previewTable(client, settings, info)),
+		{ type: "divider" },
+		...usage(),
+	];
+}
+
+export async function widget(ctx: RouteContext, now = Date.now()): Promise<Block[]> {
+	const settings = await loadSettings(ctx);
+	const client = clientFor(ctx, settings);
+	const info = await client.keyInfo();
+	const banner = connectionBanner(settings, info);
+	const stats = await client.stats();
+	return [
+		...(banner ? [banner] : []),
+		{
+			type: "fields",
+			fields: [
+				{ label: "Referral code", value: (info?.ok ? info.owner.ref : settings.refCode) || "—" },
+				{ label: "Last refresh", value: ago(stats.lastFetchAt, now) },
+			],
+		},
+		actions(true),
+	];
+}
+
+/** The `admin` route: page_load / block_action for the overview page and the widget. */
+export async function adminRoute(ctx: RouteContext): Promise<BlockResult> {
+	const input = isRecord(ctx.input) ? ctx.input : {};
+	const page = typeof input.page === "string" ? input.page : "/";
+	const isWidget = page === `widget:${WIDGET_ID}`;
+	const render = () => (isWidget ? widget(ctx) : overviewPage(ctx));
+
+	if (input.type === "block_action") {
+		const settings = await loadSettings(ctx);
+		const client = clientFor(ctx, settings);
+		if (input.action_id === "refresh_cache") {
+			await client.flush();
+			return { blocks: await render(), toast: { type: "success", message: "Products will be re-fetched from AVDEB" } };
+		}
+		if (input.action_id === "test_connection") {
+			await client.flush();
+			const info = await client.keyInfo();
+			const toast: BlockResult["toast"] = !settings.apiKey
+				? { type: "info", message: settings.refCode ? `No key saved — using referral code ${settings.refCode}` : "No key saved" }
+				: info?.ok
+					? { type: "success", message: `Connected as ${info.owner.name || "AVDEB partner"}` }
+					: { type: "error", message: `Key not accepted: ${info?.error ?? "unknown error"}` };
+			return { blocks: await render(), toast };
+		}
+	}
+	return { blocks: await render() };
+}

package/src/astro/AvdebButton.astro

@@ -0,0 +1,24 @@
+---
+/**
+ * A referral CTA to any AVDEB page in an Astro template.
+ *
+ * @example <AvdebButton href="/creators/cleo/" label="Visit my shop" variant="outline" align="center" />
+ */
+import type { Alignment, ButtonVariant } from "../constants.ts";
+import Button from "./Button.astro";
+import { loadContext } from "./load.ts";
+
+interface Props {
+	/** avdeb.com URL or a path such as "/store/cat-sticker/". Other hosts render as plain text. */
+	href: string;
+	label?: string;
+	variant?: ButtonVariant;
+	align?: Alignment;
+	class?: string;
+}
+
+const { href, label = "Shop on AVDEB", variant, align, class: className } = Astro.props;
+const context = await loadContext(Astro.locals, Astro.url);
+---
+
+<Button context={context} href={href} label={label} variant={variant} align={align} class={className} />

package/src/astro/AvdebProduct.astro

@@ -0,0 +1,49 @@
+---
+/**
+ * One featured product in an Astro template.
+ *
+ * @example <AvdebProduct handle="cat-sticker" variant="hero" badge="Editor's pick" note="I use it daily." />
+ */
+import { productRequest } from "../blocks.ts";
+import type { CardStyle, ProductVariant, Theme } from "../constants.ts";
+import Embed from "./Embed.astro";
+import { loadEmbed } from "./load.ts";
+
+interface Props {
+	/** Product handle, or a full https://avdeb.com/store/{handle}/ link. */
+	handle: string;
+	variant?: ProductVariant;
+	badge?: string;
+	note?: string;
+	ctaLabel?: string;
+	cardStyle?: CardStyle;
+	theme?: Theme;
+	hidePrice?: boolean;
+	hideCreator?: boolean;
+	headingLevel?: 2 | 3 | 4 | 5;
+	class?: string;
+}
+
+const p = Astro.props;
+const req = productRequest({ id: p.handle, variant: p.variant, badge: p.badge, note: p.note });
+const data = req.handle ? await loadEmbed(Astro.locals, Astro.url, { handle: req.handle }) : null;
+---
+
+{
+	data && (
+		<Embed
+			data={data}
+			overrides={{
+				cardStyle: p.cardStyle,
+				theme: p.theme,
+				ctaLabel: p.ctaLabel,
+				hidePrice: p.hidePrice,
+				hideCreator: p.hideCreator,
+			}}
+			viewAll={false}
+			headingLevel={p.headingLevel}
+			single={{ variant: req.variant, badge: req.badge, note: req.note }}
+			class={p.class}
+		/>
+	)
+}

package/src/astro/AvdebProducts.astro

@@ -0,0 +1,68 @@
+---
+/**
+ * Products in an Astro template.
+ *
+ * @example <AvdebProducts creator="cleo" layout="carousel" limit={8} heading="From my shop" />
+ * @example <AvdebProducts url="https://avdeb.com/category/stickers/" columns={4} />
+ */
+import { parseAvdebLink } from "../catalog.ts";
+import type { CardStyle, Layout, Theme } from "../constants.ts";
+import Embed from "./Embed.astro";
+import { loadEmbed } from "./load.ts";
+
+interface Props {
+	/** Any AVDEB creator, category or product link (source detected automatically). */
+	url?: string;
+	creator?: string;
+	tag?: string;
+	type?: string;
+	q?: string;
+	limit?: number;
+	layout?: Layout;
+	columns?: number;
+	cardStyle?: CardStyle;
+	theme?: Theme;
+	heading?: string;
+	intro?: string;
+	headingLevel?: 2 | 3 | 4 | 5;
+	viewAll?: boolean;
+	ctaLabel?: string;
+	hidePrice?: boolean;
+	hideCreator?: boolean;
+	class?: string;
+}
+
+const p = Astro.props;
+const link = parseAvdebLink(p.url);
+const query: Record<string, unknown> = {
+	creator: p.creator,
+	tag: p.tag,
+	type: p.type,
+	q: p.q,
+	limit: p.limit,
+	...(link ? { [link.kind]: link.value } : {}),
+};
+const data = await loadEmbed(Astro.locals, Astro.url, query);
+---
+
+{
+	data && (
+		<Embed
+			data={data}
+			overrides={{
+				layout: p.layout,
+				columns: p.columns,
+				cardStyle: p.cardStyle,
+				theme: p.theme,
+				ctaLabel: p.ctaLabel,
+				hidePrice: p.hidePrice,
+				hideCreator: p.hideCreator,
+			}}
+			heading={p.heading}
+			intro={p.intro}
+			headingLevel={p.headingLevel}
+			viewAll={p.viewAll ?? true}
+			class={p.class}
+		/>
+	)
+}