@ewanc26/supporters 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @ewanc26/supporters
+
+SvelteKit component library for displaying Ko-fi supporters, backed by an ATProto PDS.
+
+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.
+
+---
+
+## 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>`
+
+---
+
+## Setup
+
+### 1. Environment variables
+
+```env
+# Required — copy from ko-fi.com/manage/webhooks → Advanced → Verification Token
+KOFI_VERIFICATION_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+# 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
+```
+
+Generate an app password at your PDS under **Settings → App Passwords**.
+
+### 2. Register the webhook
+
+Go to **ko-fi.com/manage/webhooks** and set your webhook URL to:
+
+```
+https://your-domain.com/webhook
+```
+
+### 3. Add the route
+
+Copy `src/routes/webhook/+server.ts` into your SvelteKit app's routes directory.
+
+### 4. Use the component
+
+```ts
+// +page.server.ts
+import { readStore } from '@ewanc26/supporters';
+
+export const load = async () => ({
+  supporters: await readStore()
+});
+```
+
+```svelte
+<!-- +page.svelte -->
+<script lang="ts">
+  import { KofiSupporters } from '@ewanc26/supporters';
+  let { data } = $props();
+</script>
+
+<KofiSupporters supporters={data.supporters} />
+```
+
+---
+
+## Components
+
+### `<KofiSupporters>`
+
+Displays all supporters with emoji type badges (☕ donation, ⭐ subscription, 🎨 commission, 🛍️ shop order).
+
+| 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` |
+
+### `<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).

package/dist/KofiSupporters.svelte

@@ -0,0 +1,198 @@
+<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>

package/dist/KofiSupporters.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { KofiSupportersProps } from './types.js';
+declare const KofiSupporters: import("svelte").Component<KofiSupportersProps, {}, "">;
+type KofiSupporters = ReturnType<typeof KofiSupporters>;
+export default KofiSupporters;

package/dist/LunarContributors.svelte

@@ -0,0 +1,28 @@
+<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}
+/>

package/dist/LunarContributors.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { KofiSupportersProps } from './types.js';
+declare const LunarContributors: import("svelte").Component<Omit<KofiSupportersProps, "filter">, {}, "">;
+type LunarContributors = ReturnType<typeof LunarContributors>;
+export default LunarContributors;

package/dist/api.ts.bak

@@ -0,0 +1,61 @@
+/**
+ * ko-fi.tools API client for fetching top supporters.
+ *
+ * ko-fi.tools is the only third-party service providing a public REST API for
+ * Ko-fi page data. Their V2 API docs are still incomplete; once they publish
+ * them confirm the endpoint and auth scheme at:
+ *   https://ko-fi.tools/support/api-documentation
+ *
+ * Profile images are served from: https://cdn.ko-fi.tools/profile/{pageId}
+ */
+
+import type { KofiSupporter } from './types.js';
+
+/** Base URL inferred from cdn.ko-fi.tools CDN pattern and V2 launch announcement. */
+const API_BASE = 'https://api.ko-fi.tools/v2';
+
+export type KofiToolsRawSupporter = {
+	/** Ko-fi page ID for this supporter */
+	id: string;
+	/** Display name */
+	name: string;
+	/** Profile URL on ko-fi.com */
+	url?: string;
+};
+
+/**
+ * Fetches top supporters for a Ko-fi page via ko-fi.tools.
+ *
+ * @param pageId   Your Ko-fi page ID (the alphanumeric string in your Ko-fi URL,
+ *                 e.g. for ko-fi.com/A0A1B2C3 the pageId is "A0A1B2C3").
+ * @param fetchFn  Optional fetch override for use in SvelteKit `+page.server.ts`
+ *                 (pass the native `fetch` from the `load` function for cookie
+ *                 forwarding and caching hints).
+ *
+ * @throws If the network request fails or the response is not OK.
+ *
+ * TODO: Verify endpoint path + auth headers once ko-fi.tools V2 API docs land.
+ */
+export async function fetchLunarContributors(
+	pageId: string,
+	fetchFn: typeof fetch = fetch
+): Promise<KofiSupporter[]> {
+	const url = `${API_BASE}/${encodeURIComponent(pageId)}/supporters`;
+
+	const res = await fetchFn(url, {
+		headers: { Accept: 'application/json' }
+	});
+
+	if (!res.ok) {
+		throw new Error(`ko-fi.tools API error ${res.status}: ${res.statusText}`);
+	}
+
+	const raw: KofiToolsRawSupporter[] = await res.json();
+
+	return raw.map((s) => ({
+		pageId: s.id,
+		name: s.name,
+		avatarUrl: `https://cdn.ko-fi.tools/profile/${s.id}`,
+		profileUrl: s.url ?? `https://ko-fi.com/${s.id}`
+	}));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { default as KofiSupporters } from './KofiSupporters.svelte';
+export { default as LunarContributors } from './LunarContributors.svelte';
+export { readStore, appendEvent } from './store.js';
+export { parseWebhook, WebhookError } from './webhook.js';

package/dist/store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 type { KofiSupporter, KofiEventType } from './types.js';
+/** The shape of a raw record stored in the PDS. */
+export interface KofiEventRecord {
+    name: string;
+    type: KofiEventType;
+    tier?: string;
+}
+/**
+ * Read all event records from the PDS and aggregate into KofiSupporter objects.
+ * No auth required — collection is publicly readable.
+ */
+export declare function readStore(): Promise<KofiSupporter[]>;
+/**
+ * Write a single Ko-fi event as a new record.
+ * rkey is a TID generated at call time.
+ */
+export declare function appendEvent(name: string, type: KofiEventType, tier: string | null, timestamp: string): Promise<void>;

package/dist/store.js

@@ -0,0 +1,94 @@
+/**
+ * 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';
+const COLLECTION = 'uk.ewancroft.kofi.supporter';
+function requireEnv(key) {
+    const val = process.env[key];
+    if (!val)
+        throw new Error(`Missing required environment variable: ${key}`);
+    return val;
+}
+function dedupe(arr, extra) {
+    return Array.from(new Set([...arr, extra]));
+}
+/** Authenticated agent for write operations. */
+async function authedAgent() {
+    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() {
+    const did = requireEnv('ATPROTO_DID');
+    const pdsUrl = requireEnv('ATPROTO_PDS_URL');
+    const agent = new AtpAgent({ service: pdsUrl });
+    const events = [];
+    let cursor;
+    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);
+        }
+        cursor = res.data.cursor;
+    } while (cursor);
+    return aggregateEvents(events);
+}
+/** Aggregate raw event records into deduplicated KofiSupporter objects. */
+function aggregateEvents(events) {
+    const map = new Map();
+    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, type, tier, timestamp) {
+    const { agent, did } = await authedAgent();
+    const record = {
+        name,
+        type,
+        ...(tier ? { tier } : {})
+    };
+    await agent.com.atproto.repo.putRecord({
+        repo: did,
+        collection: COLLECTION,
+        rkey: generateTID(timestamp),
+        record: record
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+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;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhook.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare class WebhookError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function parseWebhook(request: Request): Promise<KofiWebhookPayload>;

package/dist/webhook.js

@@ -0,0 +1,40 @@
+/**
+ * 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)
+ */
+export class WebhookError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export async function parseWebhook(request) {
+    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;
+    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;
+}

package/lexicons/uk/ewancroft/kofi/supporter.json

@@ -0,0 +1,29 @@
+{
+  "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."
+          }
+        }
+      }
+    }
+  }
+}