feat: add Ko-fi webhook support (#125)

Co-authored-by: Anthony Fu (via agent) <reg-github-bot@antfu.me>

Author: BittuBarnwal7479

README.md

@@ -12,6 +12,7 @@ Supports:
 - [**Afdian**](https://afdian.com/)
 - [**Polar**](https://polar.sh/)
 - [**Liberapay**](https://liberapay.com/)
+- [**Ko-fi**](https://ko-fi.com/)
 
 ## Usage
 
@@ -59,6 +60,12 @@ SPONSORKIT_POLAR_ORGANIZATION=
 ; Liberapay provider.
 ; The name of the profile.
 SPONSORKIT_LIBERAPAY_LOGIN=
+
+; Ko-fi provider.
+; Copy the verification token from https://ko-fi.com/manage/webhooks
+SPONSORKIT_KOFI_VERIFICATION_TOKEN=
+; Optional event store path populated by `sponsorkit kofi-webhook`.
+SPONSORKIT_KOFI_DATA_FILE=./sponsorkit/kofi-events.json
 ```
 
 > Only one provider is required to be configured.
@@ -104,6 +111,9 @@ export default defineConfig({
   liberapay: {
     // ...
   },
+  kofi: {
+    // ...
+  },
 
   // Rendering configs
   width: 800,
@@ -160,6 +170,31 @@ const sponsors = await fetchSponsors({
 
 Check the type definition or source code for more utils available.
 
+### Ko-fi Webhooks
+
+Ko-fi provides payment webhooks instead of an API for listing sponsors. Start the
+SponsorKit receiver:
+
+```bash
+npx sponsorkit kofi-webhook
+```
+
+Expose `http://127.0.0.1:3456/kofi` through an HTTPS tunnel, then set that public
+URL on the [Ko-fi webhooks page](https://ko-fi.com/manage/webhooks). SponsorKit
+verifies the webhook token, removes the token and email before persistence,
+deduplicates retries by `message_id`, and stores events in
+`./sponsorkit/kofi-events.json`.
+
+After Ko-fi sends a payment or test payment, generate the sponsor output normally:
+
+```bash
+npx sponsorkit --force
+```
+
+Ko-fi does not send an event when a membership ends. SponsorKit therefore treats
+subscription payments as active for 35 days by default. Configure
+`kofi.subscriptionEffectivity` to change this window.
+
 ### Renderers
 
 We provide two renderers built-in:

src/cli.ts

@@ -2,13 +2,40 @@
 import type { SponsorkitConfig } from './types.ts'
 import cac from 'cac'
 import pkg from '../package.json' with { type: 'json' }
+import { loadConfig } from './configs/index.ts'
+import { DEFAULT_KOFI_DATA_FILE, startKofiWebhookServer } from './providers/kofi.ts'
 import { run } from './run.ts'
 
 const RE_FILTER = /([<>=]+)(\d+)/
 const cli = cac('sponsors-svg')
   .version(pkg.version)
   .help()
 
+cli
+  .command('kofi-webhook', 'Receive and store Ko-fi payment webhooks')
+  .option('--host <host>', 'Host to listen on', { default: '127.0.0.1' })
+  .option('--port <port>', 'Port to listen on', { default: 3456 })
+  .option('--path <path>', 'Webhook path', { default: '/kofi' })
+  .option('--data-file <file>', 'Ko-fi event store')
+  .action(async (options) => {
+    const config = await loadConfig()
+    const verificationToken = config.kofi?.verificationToken
+    if (!verificationToken) {
+      throw new Error('Ko-fi verification token is required')
+    }
+    const dataFile = options.dataFile || config.kofi?.dataFile || DEFAULT_KOFI_DATA_FILE
+    const port = Number.parseInt(options.port)
+    await startKofiWebhookServer({
+      verificationToken,
+      dataFile,
+      host: options.host,
+      port,
+      path: options.path,
+    })
+    console.log(`[sponsorkit] Ko-fi webhook listening on http://${options.host}:${port}${options.path}`)
+    console.log(`[sponsorkit] Storing sanitized events in ${resolveDisplayPath(dataFile)}`)
+  })
+
 cli
   .command('[outputDir]', 'Generate sponsors SVG')
   .option('--width, -w <width>', 'SVG width', { default: 800 })
@@ -50,3 +77,7 @@ function createFilterFromString(template: string): SponsorkitConfig['filter'] {
     return s => s.monthlyDollars >= num
   throw new Error(`Unable to parse filter template ${template}`)
 }
+
+function resolveDisplayPath(path: string) {
+  return path.replaceAll('\\', '/')
+}

src/configs/env.ts

@@ -43,6 +43,10 @@ export function loadEnv(): Partial<SponsorkitConfig> {
     liberapay: {
       login: process.env.SPONSORKIT_LIBERAPAY_LOGIN || process.env.LIBERAPAY_LOGIN,
     },
+    kofi: {
+      verificationToken: process.env.SPONSORKIT_KOFI_VERIFICATION_TOKEN || process.env.KOFI_VERIFICATION_TOKEN,
+      dataFile: process.env.SPONSORKIT_KOFI_DATA_FILE,
+    },
     outputDir: process.env.SPONSORKIT_DIR,
   }
 

src/configs/index.ts

@@ -56,6 +56,11 @@ export async function loadConfig(inlineConfig: SponsorkitConfig = {}): Promise<R
       ...config.afdian,
       ...inlineConfig.afdian,
     },
+    kofi: {
+      ...env.kofi,
+      ...config.kofi,
+      ...inlineConfig.kofi,
+    },
   } as Required<SponsorkitConfig>
 
   if (!['sponsors', 'sponsees'].includes(resolved.mode))

src/providers/index.ts

@@ -1,12 +1,14 @@
 import type { Provider, ProviderName, SponsorkitConfig } from '../types.ts'
 import { AfdianProvider } from './afdian.ts'
 import { GitHubProvider } from './github.ts'
+import { KofiProvider } from './kofi.ts'
 import { LiberapayProvider } from './liberapay.ts'
 import { OpenCollectiveProvider } from './opencollective.ts'
 import { PatreonProvider } from './patreon.ts'
 import { PolarProvider } from './polar.ts'
 
 export * from './github.ts'
+export * from './kofi.ts'
 
 export const ProvidersMap = {
   github: GitHubProvider,
@@ -15,6 +17,7 @@ export const ProvidersMap = {
   afdian: AfdianProvider,
   polar: PolarProvider,
   liberapay: LiberapayProvider,
+  kofi: KofiProvider,
 }
 
 export function guessProviders(config: SponsorkitConfig) {
@@ -37,6 +40,9 @@ export function guessProviders(config: SponsorkitConfig) {
   if (config.liberapay && config.liberapay.login)
     items.push('liberapay')
 
+  if (config.kofi && (config.kofi.verificationToken || config.kofi.dataFile))
+    items.push('kofi')
+
   // fallback
   if (!items.length)
     items.push('github')

src/providers/kofi.test.ts

@@ -0,0 +1,221 @@
+import type { AddressInfo } from 'node:net'
+import { mkdtemp, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  fetchKofiSponsors,
+  parseKofiWebhookBody,
+  startKofiWebhookServer,
+  storeKofiEvent,
+} from './kofi.ts'
+
+const servers: Awaited<ReturnType<typeof startKofiWebhookServer>>[] = []
+
+afterEach(async () => {
+  await Promise.all(servers.splice(0).map(server => new Promise<void>((resolve, reject) => {
+    server.close(error => error ? reject(error) : resolve())
+  })))
+})
+
+describe('ko-fi provider', () => {
+  it('verifies and sanitizes webhook payloads', () => {
+    const event = parseKofiWebhookBody(createBody(), 'correct-token')
+
+    expect(event).toMatchObject({
+      messageId: 'message-1',
+      timestamp: '2026-07-27T05:00:00.000Z',
+      type: 'Subscription',
+      isPublic: true,
+      fromName: 'Ada',
+      amount: 5,
+      currency: 'USD',
+      isSubscriptionPayment: true,
+      tierName: 'Gold',
+    })
+    expect(event).not.toHaveProperty('verification_token')
+    expect(event).not.toHaveProperty('email')
+  })
+
+  it('rejects a webhook with the wrong verification token', () => {
+    expect(() => parseKofiWebhookBody(createBody(), 'wrong-token'))
+      .toThrow('Invalid Ko-fi verification token')
+  })
+
+  it('scrubs the identity of private payments', () => {
+    const event = parseKofiWebhookBody(createBody({
+      is_public: false,
+      from_name: 'Private Name',
+      email: 'private@example.com',
+    }), 'correct-token')
+
+    expect(event.fromName).toBe('Private Sponsor')
+    expect(event.isPublic).toBe(false)
+  })
+
+  it('groups private subscription renewals without exposing their identity', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'sponsorkit-kofi-private-'))
+    const dataFile = join(directory, 'events.json')
+    const firstPayment = parseKofiWebhookBody(createBody({
+      message_id: 'private-payment-1',
+      timestamp: '2026-07-01T00:00:00Z',
+      is_public: false,
+      from_name: 'Private Name',
+      email: 'Private@Example.com',
+    }), 'correct-token')
+    const renewal = parseKofiWebhookBody(createBody({
+      message_id: 'private-payment-2',
+      timestamp: '2026-07-20T00:00:00Z',
+      is_public: false,
+      from_name: 'Private Name',
+      email: 'private@example.com',
+      is_first_subscription_payment: false,
+    }), 'correct-token')
+
+    expect(firstPayment.sponsorKey).toBe(renewal.sponsorKey)
+    await storeKofiEvent(firstPayment, dataFile)
+    await storeKofiEvent(renewal, dataFile)
+
+    const sponsors = await fetchKofiSponsors(
+      { dataFile },
+      Date.parse('2026-07-27T00:00:00Z'),
+    )
+    expect(sponsors).toHaveLength(1)
+    expect(sponsors[0]).toMatchObject({
+      monthlyDollars: 5,
+      privacyLevel: 'PRIVATE',
+      sponsor: { name: 'Private Sponsor' },
+    })
+  })
+
+  it('does not merge unrelated anonymous payments', () => {
+    const firstPayment = parseKofiWebhookBody(createBody({
+      message_id: 'anonymous-payment-1',
+      type: 'Tip',
+      from_name: '',
+      email: '',
+      is_subscription_payment: false,
+    }), 'correct-token')
+    const secondPayment = parseKofiWebhookBody(createBody({
+      message_id: 'anonymous-payment-2',
+      type: 'Tip',
+      from_name: '',
+      email: '',
+      is_subscription_payment: false,
+    }), 'correct-token')
+
+    expect(firstPayment.fromName).toBe('Anonymous')
+    expect(firstPayment.sponsorKey).not.toBe(secondPayment.sponsorKey)
+  })
+
+  it('keeps public and private payments from the same identity separate', () => {
+    const publicPayment = parseKofiWebhookBody(createBody(), 'correct-token')
+    const privatePayment = parseKofiWebhookBody(createBody({
+      message_id: 'private-payment',
+      is_public: false,
+    }), 'correct-token')
+
+    expect(publicPayment.sponsorKey).not.toBe(privatePayment.sponsorKey)
+  })
+
+  it('deduplicates retries and aggregates recent payments', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'sponsorkit-kofi-'))
+    const dataFile = join(directory, 'events.json')
+    const subscription = parseKofiWebhookBody(createBody({
+      timestamp: '2026-07-01T00:00:00Z',
+    }), 'correct-token')
+    const tip = parseKofiWebhookBody(createBody({
+      message_id: 'message-2',
+      timestamp: '2026-07-05T00:00:00Z',
+      type: 'Tip',
+      amount: '2',
+      is_subscription_payment: false,
+      is_first_subscription_payment: false,
+      tier_name: undefined,
+    }), 'correct-token')
+
+    expect(await storeKofiEvent(subscription, dataFile)).toBe(true)
+    expect(await storeKofiEvent(subscription, dataFile)).toBe(false)
+    expect(await storeKofiEvent(tip, dataFile)).toBe(true)
+
+    const sponsors = await fetchKofiSponsors(
+      { dataFile },
+      Date.parse('2026-07-20T00:00:00Z'),
+    )
+    expect(sponsors).toHaveLength(1)
+    expect(sponsors[0]).toMatchObject({
+      monthlyDollars: 7,
+      privacyLevel: 'PUBLIC',
+      isOneTime: false,
+      sponsor: {
+        name: 'Ada',
+        avatarUrl: '',
+      },
+    })
+  })
+
+  it('receives a live-shaped HTTP form post and persists it', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'sponsorkit-kofi-http-'))
+    const dataFile = join(directory, 'events.json')
+    const server = await startKofiWebhookServer({
+      verificationToken: 'correct-token',
+      dataFile,
+      host: '127.0.0.1',
+      port: 0,
+    })
+    servers.push(server)
+    const { port } = server.address() as AddressInfo
+
+    const response = await fetch(`http://127.0.0.1:${port}/kofi`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: createBody(),
+    })
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ ok: true, stored: true })
+    const stored = JSON.parse(await readFile(dataFile, 'utf8'))
+    expect(stored.events).toHaveLength(1)
+    expect(stored.events[0]).not.toHaveProperty('verification_token')
+  })
+
+  it('provides a browser-friendly health check', async () => {
+    const server = await startKofiWebhookServer({
+      verificationToken: 'correct-token',
+      host: '127.0.0.1',
+      port: 0,
+    })
+    servers.push(server)
+    const { port } = server.address() as AddressInfo
+
+    const response = await fetch(`http://127.0.0.1:${port}/kofi`)
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject({
+      ok: true,
+      message: expect.stringContaining('receiver is ready'),
+    })
+  })
+})
+
+function createBody(overrides: Record<string, unknown> = {}) {
+  const payload = {
+    verification_token: 'correct-token',
+    message_id: 'message-1',
+    timestamp: '2026-07-27T05:00:00Z',
+    type: 'Subscription',
+    is_public: true,
+    from_name: 'Ada',
+    message: 'Thank you',
+    amount: '5',
+    url: 'https://ko-fi.com/example',
+    email: 'ada@example.com',
+    currency: 'USD',
+    is_subscription_payment: true,
+    is_first_subscription_payment: true,
+    tier_name: 'Gold',
+    kofi_transaction_id: 'transaction-1',
+    ...overrides,
+  }
+  return new URLSearchParams({ data: JSON.stringify(payload) }).toString()
+}