feat(supporters): implement @ewanc26/supporters library

packages/supporters/README.md

···
-# Svelte library
+# @ewanc26/supporters
 
-Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
+SvelteKit component library for displaying Ko-fi supporters, backed by an ATProto PDS.
 
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+Ko-fi's webhook pushes payment events to your endpoint. Each event is stored as a record under the `uk.ewancroft.kofi.supporter` lexicon on your PDS, with a TID rkey derived from the transaction timestamp. The component reads those records and renders them.
 
-## Creating a project
+---
+
+## How it works
+
+1. Ko-fi POSTs a webhook event to `/webhook` on each transaction
+2. The handler verifies the `verification_token`, respects `is_public`, and calls `appendEvent`
+3. `appendEvent` writes a record to your PDS under `uk.ewancroft.kofi.supporter`
+4. `readStore` fetches all records and aggregates them into `KofiSupporter` objects
+5. Pass the result to `<KofiSupporters>` or `<LunarContributors>`
 
-If you're seeing this, you've probably already done this step. Congrats!
+---
 
-```sh
-# create a new project in the current directory
-npx sv create
+## Setup
 
-# create a new project in my-app
-npx sv create my-app
-```
+### 1. Environment variables
 
-To recreate this project with the same configuration:
+```env
+# Required — copy from ko-fi.com/manage/webhooks → Advanced → Verification Token
+KOFI_VERIFICATION_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
-```sh
-# recreate this project
-pnpm dlx sv@0.12.5 create --template library --types ts --add prettier tailwindcss="plugins:typography" sveltekit-adapter="adapter:auto" --install pnpm ./supporters
+# Required — your ATProto identity and a dedicated app password
+ATPROTO_DID=did:plc:yourdidhex
+ATPROTO_PDS_URL=https://your-pds.example.com
+ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
 ```
 
-## Developing
+Generate an app password at your PDS under **Settings → App Passwords**.
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+### 2. Register the webhook
 
-```sh
-npm run dev
+Go to **ko-fi.com/manage/webhooks** and set your webhook URL to:
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+```
+https://your-domain.com/webhook
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+### 3. Add the route
 
-## Building
+Copy `src/routes/webhook/+server.ts` into your SvelteKit app's routes directory.
+
+### 4. Use the component
 
-To build your library:
+```ts
+// +page.server.ts
+import { readStore } from '@ewanc26/supporters';
 
-```sh
-npm pack
+export const load = async () => ({
+  supporters: await readStore()
+});
 ```
 
-To create a production version of your showcase app:
+```svelte
+<!-- +page.svelte -->
+<script lang="ts">
+  import { KofiSupporters } from '@ewanc26/supporters';
+  let { data } = $props();
+</script>
 
-```sh
-npm run build
+<KofiSupporters supporters={data.supporters} />
 ```
 
-You can preview the production build with `npm run preview`.
+---
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+## Components
 
-## Publishing
+### `<KofiSupporters>`
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+Displays all supporters with emoji type badges (☕ donation, ⭐ subscription, 🎨 commission, 🛍️ shop order).
 
-To publish your library to [npm](https://www.npmjs.com):
+| Prop | Type | Default |
+|---|---|---|
+| `supporters` | `KofiSupporter[]` | `[]` |
+| `heading` | `string` | `'Supporters'` |
+| `description` | `string` | `'People who support my work on Ko-fi.'` |
+| `filter` | `KofiEventType[]` | `undefined` (show all) |
+| `loading` | `boolean` | `false` |
+| `error` | `string \| null` | `null` |
 
-```sh
-npm publish
+### `<LunarContributors>`
+
+Convenience wrapper around `<KofiSupporters>` pre-filtered to `Subscription` events.
+
+---
+
+## Importing historical data
+
+Export your transaction history from **ko-fi.com/manage/transactions → Export CSV**, then:
+
+```bash
+ATPROTO_DID=... ATPROTO_PDS_URL=... ATPROTO_APP_PASSWORD=... \
+  node node_modules/@ewanc26/supporters/scripts/import-history.mjs transactions.csv --dry-run
 ```
+
+---
+
+## Lexicon
+
+Records are stored under `uk.ewancroft.kofi.supporter` (see `lexicons/`). Each record contains:
+
+```ts
+{
+  name: string        // display name from Ko-fi
+  type: string        // "Donation" | "Subscription" | "Commission" | "Shop Order"
+  tier?: string       // subscription tier name, if applicable
+}
+```
+
+rkeys are TIDs derived from the transaction timestamp via [`@ewanc26/tid`](https://npmjs.com/package/@ewanc26/tid).

packages/supporters/lexicons/uk/ewancroft/kofi/supporter.json

···
+{
+  "lexicon": 1,
+  "id": "uk.ewancroft.kofi.supporter",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "A single Ko-fi payment event. One record per event, rkey is a TID.",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["name", "type"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Display name from Ko-fi."
+          },
+          "type": {
+            "type": "string",
+            "description": "Ko-fi event type: Donation, Subscription, Commission, or Shop Order."
+          },
+          "tier": {
+            "type": "string",
+            "description": "Subscription tier name, if applicable."
+          }
+        }
+      }
+    }
+  }
+}

packages/supporters/package.json

···
 {
-	"name": "supporters",
-	"version": "0.0.1",
+	"name": "@ewanc26/supporters",
+	"version": "0.1.0",
+	"description": "SvelteKit component library for displaying Ko-fi supporters, backed by an ATProto PDS.",
+	"author": "Ewan Croft",
+	"license": "AGPL-3.0-only",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
···
 	},
 	"files": [
 		"dist",
+		"lexicons",
+		"scripts",
 		"!dist/**/*.test.*",
 		"!dist/**/*.spec.*"
 	],
···
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
-			"svelte": "./dist/index.js"
+			"svelte": "./dist/index.js",
+			"default": "./dist/index.js"
 		}
 	},
+	"dependencies": {
+		"@ewanc26/tid": "^1.1.1"
+	},
 	"peerDependencies": {
+		"@atproto/api": ">=0.13.0",
 		"svelte": "^5.0.0"
 	},
 	"devDependencies": {
+		"@atproto/api": "^0.18.1",
 		"@sveltejs/adapter-auto": "^7.0.0",
 		"@sveltejs/kit": "^2.50.2",
 		"@sveltejs/package": "^2.5.7",
···
 		"vite": "^7.3.1"
 	},
 	"keywords": [
-		"svelte"
-	]
+		"svelte",
+		"atproto",
+		"ko-fi",
+		"supporters",
+		"webhook"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
 }

packages/supporters/scripts/import-history.mjs

···
+#!/usr/bin/env node
+/**
+ * Import historical Ko-fi transaction data into your PDS.
+ *
+ * Export your transactions from: ko-fi.com/manage/transactions → Export CSV
+ *
+ * Usage:
+ *   ATPROTO_DID=... ATPROTO_PDS_URL=... ATPROTO_APP_PASSWORD=... \
+ *     node scripts/import-history.mjs /path/to/kofi-transactions.csv
+ *
+ * Flags:
+ *   --dry-run   Print what would be upserted without writing to the PDS.
+ *   --skip N    Skip the first N data rows (resume after a partial import).
+ *
+ * The script is idempotent — re-running it will merge new event types and
+ * tiers into existing records rather than creating duplicates.
+ */
+
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { resolve } from 'node:path';
+
+// ── Args ─────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const csvPath = args.find((a) => !a.startsWith('--'));
+const dryRun = args.includes('--dry-run');
+const skipArg = args.find((a) => a.startsWith('--skip='));
+const skip = skipArg ? parseInt(skipArg.split('=')[1], 10) : 0;
+
+if (!csvPath) {
+	console.error('Usage: node scripts/import-history.mjs <path-to-csv> [--dry-run] [--skip=N]');
+	process.exit(1);
+}
+
+// ── Ko-fi CSV column mapping ──────────────────────────────────────────────────
+// Actual export headers (from ko-fi.com/manage/transactions):
+//   DateTime (UTC), From, Message, Item, Received, Given, Currency,
+//   TransactionType, TransactionId, Reference, SalesTax, ...
+//
+// TransactionType values seen in exports → our KofiEventType:
+//   "Tip"          → "Donation"
+//   "Monthly Tip"  → "Subscription"
+//   "Commission"   → "Commission"
+//   "Shop Order"   → "Shop Order"
+
+const TYPE_MAP = {
+	'tip': 'Donation',
+	'monthly tip': 'Subscription',
+	'commission': 'Commission',
+	'shop order': 'Shop Order',
+};
+
+function normaliseType(raw) {
+	const key = raw.trim().toLowerCase();
+	return TYPE_MAP[key] ?? raw.trim();
+}
+
+// Ko-fi's CSV header names, lowercased + spaces collapsed to underscores.
+// Used to map row fields by name rather than position.
+const COL_TIMESTAMP  = 'datetime_(utc)';
+const COL_NAME       = 'from';
+const COL_TYPE       = 'transactiontype';
+const COL_TIER       = 'item'; // only meaningful for subscriptions
+
+// ── ATProto write ────────────────────────────────────────────────────────────
+
+const COLLECTION = 'uk.ewancroft.kofi.supporter';
+
+function requireEnv(key) {
+	const val = process.env[key];
+	if (!val) { console.error(`Missing env var: ${key}`); process.exit(1); }
+	return val;
+}
+
+const { generateTID } = await import('@ewanc26/tid');
+
+async function appendEvent(agent, did, name, type, tier, timestamp) {
+	const rkey = generateTID(timestamp);
+	const record = { name, type, ...(tier ? { tier } : {}) };
+	await agent.com.atproto.repo.putRecord({ repo: did, collection: COLLECTION, rkey, record });
+	return rkey;
+}
+
+// ── CSV parser (no dependencies) ─────────────────────────────────────────────
+
+function parseCSVLine(line) {
+	const fields = [];
+	let current = '';
+	let inQuotes = false;
+
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (ch === '"') {
+			if (inQuotes && line[i + 1] === '"') { current += '"'; i++; }
+			else { inQuotes = !inQuotes; }
+		} else if (ch === ',' && !inQuotes) {
+			fields.push(current.trim());
+			current = '';
+		} else {
+			current += ch;
+		}
+	}
+	fields.push(current.trim());
+	return fields;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+const { AtpAgent } = await import('@atproto/api');
+
+let agent, did;
+
+if (!dryRun) {
+	did = requireEnv('ATPROTO_DID');
+	const pdsUrl = requireEnv('ATPROTO_PDS_URL');
+	const password = requireEnv('ATPROTO_APP_PASSWORD');
+
+	agent = new AtpAgent({ service: pdsUrl });
+	await agent.login({ identifier: did, password });
+	console.log(`✓ Logged in as ${did}\n`);
+} else {
+	console.log('DRY RUN — nothing will be written to the PDS.\n');
+}
+
+const rl = createInterface({ input: createReadStream(resolve(csvPath)), crlfDelay: Infinity });
+
+let headers = null;
+let rowIndex = 0;
+let processed = 0;
+let skipped = 0;
+let errors = 0;
+
+for await (const line of rl) {
+	if (!line.trim()) continue;
+
+	if (!headers) {
+		headers = parseCSVLine(line).map((h) => h.toLowerCase().replace(/\s+/g, '_'));
+		console.log(`Headers: ${headers.join(', ')}\n`);
+		continue;
+	}
+
+	rowIndex++;
+
+	if (rowIndex <= skip) {
+		skipped++;
+		continue;
+	}
+
+	const fields = parseCSVLine(line);
+	const row = Object.fromEntries(headers.map((h, i) => [h, fields[i] ?? '']));
+
+	const name = row[COL_NAME]?.trim();
+	const type = normaliseType(row[COL_TYPE] ?? '');
+	const rawTier = row[COL_TIER]?.trim();
+	// Only treat "Item" as a tier if it's a Subscription AND not the generic "Ko-fi Support" label.
+	const tier = type === 'Subscription' && rawTier && rawTier.toLowerCase() !== 'ko-fi support' ? rawTier : null;
+	// Ko-fi exports timestamps as "MM/DD/YYYY HH:MM" UTC — convert to ISO 8601.
+	const rawTs = row[COL_TIMESTAMP]?.trim();
+	const timestamp = rawTs ? new Date(rawTs + ' UTC').toISOString() : new Date().toISOString();
+
+	if (!name) {
+		console.warn(`Row ${rowIndex}: empty name, skipping.`);
+		errors++;
+		continue;
+	}
+
+	if (dryRun) {
+		const rkey = generateTID(timestamp);
+		console.log(`[${rowIndex}] ${rkey}  ${name} · ${type}${tier ? ` · ${tier}` : ''}`);
+		processed++;
+		continue;
+	}
+
+	try {
+		const rkey = await appendEvent(agent, did, name, type, tier, timestamp);
+		console.log(`[${rowIndex}] ${rkey} ${name} · ${type}${tier ? ` · ${tier}` : ''}`);
+		processed++;
+	} catch (err) {
+		console.error(`[${rowIndex}] ERROR for "${name}": ${err.message}`);
+		errors++;
+	}
+}
+
+console.log(`\n─────────────────────────────`);
+console.log(`Processed : ${processed}`);
+if (skipped) console.log(`Skipped   : ${skipped} (--skip=${skip})`);
+if (errors)  console.log(`Errors    : ${errors}`);
+console.log(`─────────────────────────────`);

packages/supporters/scripts/probe-api.mjs

···
+#!/usr/bin/env node
+/**
+ * Probe the ko-fi.tools API for a given Ko-fi page ID.
+ *
+ * Usage:
+ *   node scripts/probe-api.mjs YOUR_KOFI_PAGE_ID
+ *
+ * If the endpoint path is wrong, update API_BASE / path in src/lib/api.ts
+ * once the ko-fi.tools V2 docs are published.
+ */
+
+const pageId = process.argv[2];
+
+if (!pageId) {
+	console.error('Usage: node scripts/probe-api.mjs YOUR_KOFI_PAGE_ID');
+	process.exit(1);
+}
+
+const API_BASE = 'https://api.ko-fi.tools/v2';
+const url = `${API_BASE}/${encodeURIComponent(pageId)}/supporters`;
+
+console.log(`→ GET ${url}\n`);
+
+try {
+	const res = await fetch(url, { headers: { Accept: 'application/json' } });
+	console.log(`Status: ${res.status} ${res.statusText}`);
+	console.log('Headers:', Object.fromEntries(res.headers.entries()));
+
+	const body = await res.text();
+	try {
+		console.log('\nBody (parsed):', JSON.stringify(JSON.parse(body), null, 2));
+	} catch {
+		console.log('\nBody (raw):', body);
+	}
+} catch (err) {
+	console.error('Network error:', err.message);
+}

packages/supporters/scripts/probe-endpoints.mjs

···
+#!/usr/bin/env node
+/**
+ * Probe multiple candidate ko-fi.tools API endpoint patterns.
+ * Usage: node scripts/probe-endpoints.mjs YOUR_KOFI_PAGE_ID
+ */
+
+const pageId = process.argv[2] ?? 'ewancroft';
+
+const candidates = [
+	`https://api.ko-fi.tools/v2/${pageId}/supporters`,
+	`https://api.ko-fi.tools/v2/${pageId}/top-supporters`,
+	`https://api.ko-fi.tools/v2/supporters/${pageId}`,
+	`https://api.ko-fi.tools/${pageId}/supporters`,
+	`https://api.ko-fi.tools/${pageId}`,
+	`https://api.ko-fi.tools/v2/${pageId}`,
+	`https://api.ko-fi.tools/v1/${pageId}/supporters`,
+	`https://api.ko-fi.tools/v1/${pageId}/top`,
+	`https://ko-fi.tools/api/${pageId}/supporters`,
+	`https://ko-fi.tools/api/v2/${pageId}/supporters`,
+];
+
+for (const url of candidates) {
+	try {
+		const res = await fetch(url, { headers: { Accept: 'application/json' } });
+		const body = await res.text();
+		let parsed;
+		try { parsed = JSON.parse(body); } catch { parsed = body.slice(0, 120); }
+		console.log(`${res.status} ${url}`);
+		if (res.status !== 404) console.log('       →', JSON.stringify(parsed).slice(0, 200));
+	} catch (e) {
+		console.log(`ERR  ${url} — ${e.message}`);
+	}
+}

packages/supporters/scripts/simulate-webhook.mjs

···
+#!/usr/bin/env node
+/**
+ * Simulate Ko-fi webhook POSTs against your local dev server.
+ *
+ * Usage:
+ *   KOFI_VERIFICATION_TOKEN=your-token node scripts/simulate-webhook.mjs [type] [name] [tier]
+ *
+ * Types: Donation | Subscription | Commission | "Shop Order"
+ *
+ * Examples:
+ *   node scripts/simulate-webhook.mjs Donation "Jo Example"
+ *   node scripts/simulate-webhook.mjs Subscription "Alice" "Lunar Contributors"
+ *   node scripts/simulate-webhook.mjs Commission "Bob"
+ *   node scripts/simulate-webhook.mjs "Shop Order" "Carol"
+ */
+
+const token = process.env.KOFI_VERIFICATION_TOKEN ?? 'test-token';
+const type = process.argv[2] ?? 'Donation';
+const name = process.argv[3] ?? 'Jo Example';
+const tier = process.argv[4] ?? (type === 'Subscription' ? 'Lunar Contributors' : null);
+const url = process.argv[5] ?? 'http://localhost:5173/webhook';
+
+const isSubscription = type === 'Subscription';
+
+const payload = {
+	verification_token: token,
+	message_id: crypto.randomUUID(),
+	timestamp: new Date().toISOString(),
+	type,
+	is_public: true,
+	from_name: name,
+	message: 'Simulated webhook event',
+	amount: '3.00',
+	url: 'https://ko-fi.com/Home/CoffeeShop?txid=test',
+	email: '[e-mail]',
+	currency: 'GBP',
+	is_subscription_payment: isSubscription,
+	is_first_subscription_payment: isSubscription,
+	kofi_transaction_id: crypto.randomUUID(),
+	shop_items: type === 'Shop Order' ? [{ id: 'item-1', name: 'Test Item' }] : null,
+	tier_name: tier ?? null,
+	shipping: null
+};
+
+const body = new URLSearchParams({ data: JSON.stringify(payload) });
+
+console.log(`→ POST ${url}`);
+console.log(`  type:      ${type}`);
+console.log(`  from_name: ${name}`);
+if (tier) console.log(`  tier_name: ${tier}`);
+console.log();
+
+const res = await fetch(url, {
+	method: 'POST',
+	headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+	body
+});
+
+console.log(`Status: ${res.status} ${res.statusText}`);
+if (res.status !== 200) {
+	console.log('Body:', await res.text());
+}

packages/supporters/src/lib/KofiSupporters.svelte

···
+<script lang="ts">
+	import type { KofiSupportersProps, KofiEventType } from './types.js';
+
+	let {
+		supporters = [],
+		heading = 'Supporters',
+		description = 'People who support my work on Ko-fi.',
+		filter = undefined,
+		loading = false,
+		error = null
+	}: KofiSupportersProps = $props();
+
+	const TYPE_LABELS: Record<KofiEventType, string> = {
+		Donation: '☕',
+		Subscription: '⭐',
+		Commission: '🎨',
+		'Shop Order': '🛍️'
+	};
+
+	let visible = $derived(
+		filter
+			? supporters.filter((s) => s.types.some((t) => filter!.includes(t)))
+			: supporters
+	);
+
+	/** Deterministic pastel colour from a name string. */
+	function nameToHsl(name: string): string {
+		let hash = 0;
+		for (let i = 0; i < name.length; i++) hash = name.charCodeAt(i) + ((hash << 5) - hash);
+		const h = Math.abs(hash) % 360;
+		return `hsl(${h} 55% 70%)`;
+	}
+
+	/** Initials from a display name. */
+	function initials(name: string): string {
+		return name
+			.split(/\s+/)
+			.slice(0, 2)
+			.map((w) => w[0]?.toUpperCase() ?? '')
+			.join('');
+	}
+</script>
+
+<section class="kofi-supporters" aria-label={heading}>
+	<header class="kofi-supporters__header">
+		<h2 class="kofi-supporters__heading">{heading}</h2>
+		{#if description}
+			<p class="kofi-supporters__description">{description}</p>
+		{/if}
+	</header>
+
+	{#if loading}
+		<ul class="kofi-supporters__grid" aria-busy="true" aria-label="Loading supporters">
+			{#each { length: 6 } as _}
+				<li class="kofi-supporters__item kofi-supporters__item--skeleton" aria-hidden="true">
+					<span class="kofi-supporters__avatar kofi-supporters__avatar--skeleton"></span>
+					<span class="kofi-supporters__name kofi-supporters__name--skeleton"></span>
+				</li>
+			{/each}
+		</ul>
+	{:else if error}
+		<p class="kofi-supporters__error" role="alert">{error}</p>
+	{:else if visible.length === 0}
+		<p class="kofi-supporters__empty">No supporters yet — be the first!</p>
+	{:else}
+		<ul class="kofi-supporters__grid">
+			{#each visible as supporter (supporter.name)}
+				{@const typeIcons = supporter.types.map((t) => TYPE_LABELS[t]).join('')}
+				<li class="kofi-supporters__item">
+					<span
+						class="kofi-supporters__card"
+						title="{supporter.name} · {supporter.types.join(', ')}{supporter.tiers.length ? ` · ${supporter.tiers.join(', ')}` : ''}"
+					>
+						<span
+							class="kofi-supporters__avatar"
+							style="background-color: {nameToHsl(supporter.name)}"
+							aria-hidden="true"
+						>
+							{initials(supporter.name)}
+						</span>
+						<span class="kofi-supporters__name">{supporter.name}</span>
+						<span class="kofi-supporters__icons" aria-label={supporter.types.join(', ')}>{typeIcons}</span>
+					</span>
+				</li>
+			{/each}
+		</ul>
+	{/if}
+</section>
+
+<style>
+	.kofi-supporters {
+		container-type: inline-size;
+	}
+
+	.kofi-supporters__header {
+		margin-block-end: 1rem;
+	}
+
+	.kofi-supporters__heading {
+		font-size: 1.25rem;
+		font-weight: 700;
+		margin: 0;
+	}
+
+	.kofi-supporters__description {
+		margin-block-start: 0.25rem;
+		font-size: 0.875rem;
+		opacity: 0.75;
+	}
+
+	.kofi-supporters__grid {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.75rem;
+		list-style: none;
+		margin: 0;
+		padding: 0;
+	}
+
+	.kofi-supporters__card {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: 0.25rem;
+		padding: 0.5rem;
+		border-radius: 0.5rem;
+		cursor: default;
+	}
+
+	.kofi-supporters__avatar {
+		width: 3rem;
+		height: 3rem;
+		border-radius: 50%;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		font-size: 1rem;
+		font-weight: 700;
+		color: #fff;
+		flex-shrink: 0;
+	}
+
+	.kofi-supporters__name {
+		font-size: 0.75rem;
+		text-align: center;
+		max-width: 5rem;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.kofi-supporters__icons {
+		font-size: 0.65rem;
+		line-height: 1;
+	}
+
+	/* Skeletons */
+	.kofi-supporters__item--skeleton {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: 0.375rem;
+		padding: 0.5rem;
+	}
+
+	.kofi-supporters__avatar--skeleton {
+		display: block;
+		width: 3rem;
+		height: 3rem;
+		border-radius: 50%;
+		background-color: color-mix(in srgb, currentColor 15%, transparent);
+		animation: ks-pulse 1.4s ease-in-out infinite;
+	}
+
+	.kofi-supporters__name--skeleton {
+		display: block;
+		width: 4rem;
+		height: 0.75rem;
+		border-radius: 0.25rem;
+		background-color: color-mix(in srgb, currentColor 15%, transparent);
+		animation: ks-pulse 1.4s ease-in-out 200ms infinite;
+	}
+
+	@keyframes ks-pulse {
+		0%, 100% { opacity: 1; }
+		50% { opacity: 0.4; }
+	}
+
+	.kofi-supporters__error,
+	.kofi-supporters__empty {
+		font-size: 0.875rem;
+		opacity: 0.75;
+	}
+
+	.kofi-supporters__error {
+		color: #c0392b;
+	}
+</style>

packages/supporters/src/lib/LunarContributors.svelte

···
+<script lang="ts">
+	/**
+	 * Convenience wrapper around KofiSupporters pre-filtered to Subscription
+	 * events, with the "Lunar Contributors" heading.
+	 *
+	 * Equivalent to:
+	 *   <KofiSupporters filter={['Subscription']} heading="Lunar Contributors" />
+	 */
+	import KofiSupporters from './KofiSupporters.svelte';
+	import type { KofiSupportersProps } from './types.js';
+
+	let {
+		supporters = [],
+		heading = 'Lunar Contributors',
+		description = 'People who support my work on Ko-fi.',
+		loading = false,
+		error = null
+	}: Omit<KofiSupportersProps, 'filter'> = $props();
+</script>
+
+<KofiSupporters
+	{supporters}
+	{heading}
+	{description}
+	filter={['Subscription']}
+	{loading}
+	{error}
+/>

packages/supporters/src/lib/index.ts

···
-// Reexport your entry components here
+export { default as KofiSupporters } from './KofiSupporters.svelte';
+export { default as LunarContributors } from './LunarContributors.svelte';
+export { readStore, appendEvent } from './store.js';
+export type { KofiEventRecord } from './store.js';
+export { parseWebhook, WebhookError } from './webhook.js';
+export type { KofiSupporter, KofiWebhookPayload, KofiSupportersProps, KofiEventType } from './types.js';

packages/supporters/src/lib/store.ts

···
+/**
+ * ATProto PDS store for Ko-fi supporter data.
+ *
+ * Each Ko-fi event is stored as a separate record under:
+ *   uk.ewancroft.kofi.supporter
+ *
+ * rkeys are TIDs generated by @ewanc26/tid — one record per event.
+ * The aggregated KofiSupporter view (deduped by name) is built at read time.
+ *
+ * Reads are public (no auth). Writes use an app password.
+ *
+ * Required environment variables:
+ *   ATPROTO_DID           — your DID, e.g. did:plc:abc123
+ *   ATPROTO_PDS_URL       — your PDS URL, e.g. https://pds.ewancroft.uk
+ *   ATPROTO_APP_PASSWORD  — an app password from your PDS settings
+ */
+
+import { AtpAgent } from '@atproto/api';
+import { generateTID } from '@ewanc26/tid';
+import type { KofiSupporter, KofiEventType } from './types.js';
+
+const COLLECTION = 'uk.ewancroft.kofi.supporter';
+
+/** The shape of a raw record stored in the PDS. */
+export interface KofiEventRecord {
+	name: string;
+	type: KofiEventType;
+	tier?: string;
+}
+
+function requireEnv(key: string): string {
+	const val = process.env[key];
+	if (!val) throw new Error(`Missing required environment variable: ${key}`);
+	return val;
+}
+
+function dedupe<T>(arr: T[], extra: T): T[] {
+	return Array.from(new Set([...arr, extra]));
+}
+
+/** Authenticated agent for write operations. */
+async function authedAgent(): Promise<{ agent: AtpAgent; did: string }> {
+	const did = requireEnv('ATPROTO_DID');
+	const pdsUrl = requireEnv('ATPROTO_PDS_URL');
+	const password = requireEnv('ATPROTO_APP_PASSWORD');
+
+	const agent = new AtpAgent({ service: pdsUrl });
+	await agent.login({ identifier: did, password });
+	return { agent, did };
+}
+
+/**
+ * Read all event records from the PDS and aggregate into KofiSupporter objects.
+ * No auth required — collection is publicly readable.
+ */
+export async function readStore(): Promise<KofiSupporter[]> {
+	const did = requireEnv('ATPROTO_DID');
+	const pdsUrl = requireEnv('ATPROTO_PDS_URL');
+
+	const agent = new AtpAgent({ service: pdsUrl });
+
+	const events: KofiEventRecord[] = [];
+	let cursor: string | undefined;
+
+	do {
+		const res = await agent.com.atproto.repo.listRecords({
+			repo: did,
+			collection: COLLECTION,
+			limit: 100,
+			cursor
+		});
+
+		for (const record of res.data.records) {
+			events.push(record.value as unknown as KofiEventRecord);
+		}
+
+		cursor = res.data.cursor;
+	} while (cursor);
+
+	return aggregateEvents(events);
+}
+
+/** Aggregate raw event records into deduplicated KofiSupporter objects. */
+function aggregateEvents(events: KofiEventRecord[]): KofiSupporter[] {
+	const map = new Map<string, KofiSupporter>();
+
+	for (const event of events) {
+		const existing = map.get(event.name);
+		map.set(event.name, {
+			name: event.name,
+			types: dedupe(existing?.types ?? [], event.type),
+			tiers: event.tier
+				? dedupe(existing?.tiers ?? [], event.tier)
+				: (existing?.tiers ?? [])
+		});
+	}
+
+	return Array.from(map.values());
+}
+
+/**
+ * Write a single Ko-fi event as a new record.
+ * rkey is a TID generated at call time.
+ */
+export async function appendEvent(
+	name: string,
+	type: KofiEventType,
+	tier: string | null,
+	timestamp: string
+): Promise<void> {
+	const { agent, did } = await authedAgent();
+
+	const record: KofiEventRecord = {
+		name,
+		type,
+		...(tier ? { tier } : {})
+	};
+
+	await agent.com.atproto.repo.putRecord({
+		repo: did,
+		collection: COLLECTION,
+		rkey: generateTID(timestamp),
+		record: record as unknown as { [x: string]: unknown }
+	});
+}

packages/supporters/src/lib/types.ts

···
+export type KofiEventType = 'Donation' | 'Subscription' | 'Commission' | 'Shop Order';
+
+/**
+ * Ko-fi webhook payload — sent as application/x-www-form-urlencoded.
+ * The `data` field is a JSON string containing this structure.
+ *
+ * @see https://ko-fi.com/manage/webhooks
+ */
+export interface KofiWebhookPayload {
+	verification_token: string;
+	message_id: string;
+	timestamp: string;
+	type: KofiEventType;
+	is_public: boolean;
+	from_name: string;
+	message: string | null;
+	amount: string;
+	url: string;
+	email: string;
+	currency: string;
+	is_subscription_payment: boolean;
+	is_first_subscription_payment: boolean;
+	kofi_transaction_id: string;
+	shop_items: unknown | null;
+	tier_name: string | null;
+	shipping: unknown | null;
+}
+
+/** A persisted supporter record, derived from one or more webhook events. */
+export interface KofiSupporter {
+	/** Display name from the Ko-fi payment */
+	name: string;
+	/** All event types seen from this person (deduplicated) */
+	types: KofiEventType[];
+	/** All tier names seen from this person (deduplicated, non-null) */
+	tiers: string[];
+}
+
+export interface KofiSupportersProps {
+	supporters: KofiSupporter[];
+	heading?: string;
+	description?: string;
+	/** If set, only show supporters who have at least one event of these types */
+	filter?: KofiEventType[];
+	loading?: boolean;
+	error?: string | null;
+}

packages/supporters/src/lib/webhook.ts

···
+/**
+ * Validates and parses an incoming Ko-fi webhook request.
+ *
+ * Ko-fi sends application/x-www-form-urlencoded with a single `data` field
+ * containing the payment JSON. We verify the embedded verification_token
+ * matches the secret set in KOFI_VERIFICATION_TOKEN.
+ *
+ * @see https://ko-fi.com/manage/webhooks  (Advanced → Verification Token)
+ */
+
+import type { KofiWebhookPayload } from './types.js';
+
+export class WebhookError extends Error {
+	constructor(
+		message: string,
+		public readonly status: number
+	) {
+		super(message);
+	}
+}
+
+export async function parseWebhook(request: Request): Promise<KofiWebhookPayload> {
+	const secret = process.env.KOFI_VERIFICATION_TOKEN;
+	if (!secret) throw new WebhookError('KOFI_VERIFICATION_TOKEN is not set', 500);
+
+	const contentType = request.headers.get('content-type') ?? '';
+	if (!contentType.includes('application/x-www-form-urlencoded')) {
+		throw new WebhookError('Unexpected content-type', 400);
+	}
+
+	const body = await request.formData();
+	const raw = body.get('data');
+	if (!raw || typeof raw !== 'string') throw new WebhookError('Missing data field', 400);
+
+	let payload: KofiWebhookPayload;
+	try {
+		payload = JSON.parse(raw);
+	} catch {
+		throw new WebhookError('Invalid JSON in data field', 400);
+	}
+
+	if (payload.verification_token !== secret) {
+		throw new WebhookError('Verification token mismatch', 401);
+	}
+
+	return payload;
+}

packages/supporters/src/routes/+page.server.ts

···
+import { readStore } from '$lib/store.js';
+import type { PageServerLoad } from './$types.js';
+
+export const load: PageServerLoad = async () => {
+	return { supporters: await readStore() };
+};

packages/supporters/src/routes/+page.svelte

···
-<h1>Welcome to your library project</h1>
-<p>Create your package using @sveltejs/package and preview/showcase your work with SvelteKit</p>
-<p>Visit <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> to read the documentation</p>
+<script lang="ts">
+	import KofiSupporters from '$lib/KofiSupporters.svelte';
+	import type { PageData } from './$types.js';
+
+	let { data }: { data: PageData } = $props();
+</script>
+
+<KofiSupporters supporters={data.supporters} heading="All Supporters" />

packages/supporters/src/routes/webhook/+server.ts

···
+import { json } from '@sveltejs/kit';
+import { parseWebhook, WebhookError } from '$lib/webhook.js';
+import { appendEvent } from '$lib/store.js';
+import type { RequestHandler } from './$types.js';
+
+export const POST: RequestHandler = async ({ request }) => {
+	let payload;
+	try {
+		payload = await parseWebhook(request);
+	} catch (err) {
+		if (err instanceof WebhookError) {
+			return json({ error: err.message }, { status: err.status });
+		}
+		throw err;
+	}
+
+	// Respect the supporter's privacy preference.
+	if (!payload.is_public) {
+		return new Response(null, { status: 200 });
+	}
+
+	await appendEvent(
+		payload.from_name,
+		payload.type,
+		payload.tier_name,
+		payload.timestamp
+	);
+
+	// Ko-fi retries if it doesn't receive 200.
+	return new Response(null, { status: 200 });
+};

pnpm-lock.yaml

···
         specifier: ^7.3.1
         version: 7.3.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.31.1)
 
+  packages/supporters:
+    dependencies:
+      '@ewanc26/tid':
+        specifier: ^1.1.1
+        version: 1.1.1
+    devDependencies:
+      '@atproto/api':
+        specifier: ^0.18.1
+        version: 0.18.21
+      '@sveltejs/adapter-auto':
+        specifier: ^7.0.0
+        version: 7.0.1(@sveltejs/kit@2.53.4(@sveltejs/vite-plugin-svelte@6.2.4(svelte@5.53.7)(vite@7.3.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.31.1)))(svelte@5.53.7)(typescript@5.9.3)(vite@7.3.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.31.1)))
+      '@sveltejs/kit':
+        specifier: ^2.50.2
+        version: 2.53.4(@sveltejs/vite-plugin-svelte@6.2.4(svelte@5.53.7)(vite@7.3.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.31.1)))(svelte@5.53.7)(typescript@5.9.3)(vite@7.3.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.31.1))
+      '@sveltejs/package':
+        specifier: ^2.5.7
+        version: 2.5.7(svelte@5.53.7)(typescript@5.9.3)
+      '@sveltejs/vite-plugin-svelte':
+        specifier: ^6.2.4
+        version: 6.2.4(svelte@5.53.7)(vite@7.3.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.31.1))
+      '@tailwindcss/typography':
+        specifier: ^0.5.19
+        version: 0.5.19(tailwindcss@4.2.1)
+      '@tailwindcss/vite':
+        specifier: ^4.1.18
+        version: 4.2.1(vite@7.3.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.31.1))
+      prettier:
+        specifier: ^3.8.1
+        version: 3.8.1
+      prettier-plugin-svelte:
+        specifier: ^3.4.1
+        version: 3.5.1(prettier@3.8.1)(svelte@5.53.7)
+      prettier-plugin-tailwindcss:
+        specifier: ^0.7.2
+        version: 0.7.2(prettier-plugin-svelte@3.5.1(prettier@3.8.1)(svelte@5.53.7))(prettier@3.8.1)
+      publint:
+        specifier: ^0.3.17
+        version: 0.3.18
+      svelte:
+        specifier: ^5.51.0
+        version: 5.53.7
+      svelte-check:
+        specifier: ^4.4.2
+        version: 4.4.4(picomatch@4.0.3)(svelte@5.53.7)(typescript@5.9.3)
+      tailwindcss:
+        specifier: ^4.1.18
+        version: 4.2.1
+      typescript:
+        specifier: ^5.9.3
+        version: 5.9.3
+      vite:
+        specifier: ^7.3.1
+        version: 7.3.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.31.1)
+
   packages/svelte-standard-site:
     dependencies:
       '@atproto/api':
···
     engines: {node: '>=18'}
     cpu: [x64]
     os: [win32]
+
+  '@ewanc26/tid@1.1.1':
+    resolution: {integrity: sha512-u/Ks251B+5Dy1lx1PC814mWpMg2TNly4b+bHMdLCz4TwiArD/se3iApL+L6pl16eKQQlqWS2yrVKhhSwThC3WA==}
 
   '@jridgewell/gen-mapping@0.3.13':
     resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
···
 
   '@esbuild/win32-x64@0.27.3':
     optional: true
+
+  '@ewanc26/tid@1.1.1': {}
 
   '@jridgewell/gen-mapping@0.3.13':
     dependencies: