@ewanc26/supporters 0.1.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "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",
+  "files": [
+    "dist",
+    "lexicons",
+    "scripts",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "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",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tailwindcss/vite": "^4.1.18",
+    "prettier": "^3.8.1",
+    "prettier-plugin-svelte": "^3.4.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "publint": "^0.3.17",
+    "svelte": "^5.51.0",
+    "svelte-check": "^4.4.2",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  },
+  "keywords": [
+    "svelte",
+    "atproto",
+    "ko-fi",
+    "supporters",
+    "webhook"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && npm run prepack",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "lint": "prettier --check .",
+    "format": "prettier --write ."
+  }
+}

package/scripts/import-history.mjs

@@ -0,0 +1,189 @@
+#!/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(`─────────────────────────────`);

package/scripts/probe-api.mjs

@@ -0,0 +1,37 @@
+#!/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);
+}

package/scripts/probe-endpoints.mjs

@@ -0,0 +1,33 @@
+#!/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}`);
+	}
+}

package/scripts/simulate-webhook.mjs

@@ -0,0 +1,62 @@
+#!/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: 'test@example.com',
+	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());
+}