feat: sponsees mode (#113)

Author: hyoban

README.md

@@ -22,6 +22,10 @@ Create `.env` file with:
 ; Token requires the `read:user` and `read:org` scopes.
 SPONSORKIT_GITHUB_TOKEN=
 SPONSORKIT_GITHUB_LOGIN=
+; Optional data mode:
+; - sponsors: people sponsoring you (default)
+; - sponsees: people you have sponsored, including past sponsorships
+SPONSORKIT_MODE=sponsors
 
 ; Patreon provider.
 ; Create v2 API key at https://www.patreon.com/portal/registration/register-clients
@@ -75,6 +79,11 @@ Create `sponsorkit.config.js` file with:
 import { defineConfig, tierPresets } from 'sponsorkit'
 
 export default defineConfig({
+  // Data mode:
+  // - sponsors: people sponsoring you (default)
+  // - sponsees: people you have sponsored, including past sponsorships
+  mode: 'sponsors',
+
   // Providers configs
   github: {
     login: 'antfu',

src/configs/defaults.ts

@@ -45,12 +45,13 @@ text {
 `
 
 export const defaultConfig: SponsorkitConfig = {
+  mode: 'sponsors',
   width: 800,
   outputDir: './sponsorkit',
   cacheFile: '.cache.json',
+  cacheFileSponsees: '.cache.sponsees.json',
   formats: ['json', 'svg', 'png'],
   tiers: defaultTiers,
-  name: 'sponsors',
   includePrivate: false,
   svgInlineCSS: defaultInlineCSS,
 }

src/configs/env.ts

@@ -13,6 +13,7 @@ export function loadEnv(): Partial<SponsorkitConfig> {
   dotenv.config({ quiet: true })
 
   const config: Partial<SponsorkitConfig> = {
+    mode: process.env.SPONSORKIT_MODE as SponsorkitConfig['mode'] | undefined,
     github: {
       login: process.env.SPONSORKIT_GITHUB_LOGIN || process.env.GITHUB_LOGIN || getDeprecatedEnv('SPONSORKIT_LOGIN', 'SPONSORKIT_GITHUB_LOGIN'),
       token: process.env.SPONSORKIT_GITHUB_TOKEN || process.env.GITHUB_TOKEN || getDeprecatedEnv('SPONSORKIT_TOKEN', 'SPONSORKIT_GITHUB_TOKEN'),

src/configs/index.ts

@@ -58,6 +58,11 @@ export async function loadConfig(inlineConfig: SponsorkitConfig = {}): Promise<R
     },
   } as Required<SponsorkitConfig>
 
+  if (!['sponsors', 'sponsees'].includes(resolved.mode))
+    throw new Error(`Invalid mode: ${resolved.mode}. Expected "sponsors" or "sponsees".`)
+
+  resolved.name = inlineConfig.name || config.name || env.name || resolved.mode
+
   return resolved
 }
 

src/providers/afdian.ts

@@ -7,6 +7,11 @@ import { $fetch } from 'ofetch'
 export const AfdianProvider: Provider = {
   name: 'afdian',
   fetchSponsors(config) {
+    if (config.mode === 'sponsees') {
+      console.warn('[sponsorkit] Afdian provider does not support `mode: "sponsees"` yet')
+      return Promise.resolve([])
+    }
+
     return fetchAfdianSponsors(config.afdian)
   },
 }

src/providers/github.ts

@@ -40,6 +40,14 @@ const graphql = String.raw
 export const GitHubProvider: Provider = {
   name: 'github',
   fetchSponsors(config) {
+    if (config.mode === 'sponsees') {
+      return fetchGitHubSponsoringAsSponsorships(
+        config.github?.token || config.token!,
+        config.github?.login || config.login!,
+        config.github?.type || 'user',
+      )
+    }
+
     return fetchGitHubSponsors(
       config.github?.token || config.token!,
       config.github?.login || config.login!,
@@ -176,3 +184,309 @@ export function makeQuery(
   }
 }`
 }
+
+export interface GitHubSponsoringRecord {
+  sponsorable: {
+    type: 'User' | 'Organization'
+    login: string
+    name: string
+    avatarUrl: string
+    websiteUrl?: string
+    linkUrl: string
+  }
+  monthlyDollars: number
+  monthlyCents: number
+  tierName: string
+  isOneTime: boolean
+  privacyLevel?: 'PUBLIC' | 'PRIVATE'
+  createdAt: string
+  isActive: boolean
+  raw: any
+}
+
+export interface GitHubSponsoringTotalOptions {
+  since?: string
+  until?: string
+  sponsorableLogins?: string[]
+}
+
+function assertGitHubSponsoringParams(
+  token: string,
+  login: string,
+  type: GitHubAccountType,
+) {
+  if (!token)
+    throw new Error('GitHub token is required')
+  if (!login)
+    throw new Error('GitHub login is required')
+  if (!['user', 'organization'].includes(type))
+    throw new Error('GitHub type must be either `user` or `organization`')
+}
+
+async function requestGitHubSponsoringGraphQL(token: string, query: string): Promise<any> {
+  const data = await $fetch(API, {
+    method: 'POST',
+    body: { query },
+    headers: {
+      'Authorization': `bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+  }) as any
+
+  if (!data)
+    throw new Error(`Get no response on requesting ${API}`)
+  else if (data.errors?.[0]?.type === 'INSUFFICIENT_SCOPES')
+    throw new Error('Token is missing the `read:user` and/or `read:org` scopes')
+  else if (data.errors?.length)
+    throw new Error(`GitHub API error:\n${JSON.stringify(data.errors, null, 2)}`)
+
+  return data
+}
+
+async function fetchGitHubSponsoringNodes(
+  token: string,
+  login: string,
+  type: GitHubAccountType,
+  activeOnly: boolean,
+): Promise<any[]> {
+  const nodes: any[] = []
+  let cursor: string | undefined
+
+  do {
+    const query = makeSponsoringQuery(login, type, activeOnly, cursor)
+    const data = await requestGitHubSponsoringGraphQL(token, query)
+    const page = data.data?.[type]?.sponsorshipsAsSponsor
+    if (!page)
+      throw new Error('Invalid GitHub response: `sponsorshipsAsSponsor` is missing')
+
+    nodes.push(...(page.nodes || []))
+    cursor = page.pageInfo?.hasNextPage
+      ? page.pageInfo.endCursor
+      : undefined
+  } while (cursor)
+
+  return nodes
+}
+
+function toGitHubSponsoringRecord(raw: any): GitHubSponsoringRecord {
+  return {
+    sponsorable: {
+      type: raw.sponsorable.__typename,
+      login: raw.sponsorable.login,
+      name: raw.sponsorable.name || raw.sponsorable.login,
+      avatarUrl: raw.sponsorable.avatarUrl,
+      websiteUrl: normalizeUrl(raw.sponsorable.websiteUrl),
+      linkUrl: `https://github.com/${raw.sponsorable.login}`,
+    },
+    monthlyDollars: raw.tier.monthlyPriceInDollars,
+    monthlyCents: raw.tier.monthlyPriceInCents,
+    tierName: raw.tier.name,
+    isOneTime: raw.tier.isOneTime,
+    privacyLevel: raw.privacyLevel,
+    createdAt: raw.createdAt,
+    isActive: raw.isActive,
+    raw,
+  }
+}
+
+function groupSponsoringRecordsByLogin(records: GitHubSponsoringRecord[]) {
+  const recordsBySponsorable = new Map<string, GitHubSponsoringRecord[]>()
+  for (const record of records) {
+    const list = recordsBySponsorable.get(record.sponsorable.login)
+    if (list)
+      list.push(record)
+    else
+      recordsBySponsorable.set(record.sponsorable.login, [record])
+  }
+  return recordsBySponsorable
+}
+
+async function fetchTotalCentsBySponsorable(
+  token: string,
+  login: string,
+  type: GitHubAccountType,
+  sponsorableLogins: string[],
+) {
+  return new Map(
+    await Promise.all(
+      sponsorableLogins.map(async (sponsorableLogin) => {
+        const totalInCents = await fetchGitHubTotalSponsorshipAmountAsSponsor(
+          token,
+          login,
+          type,
+          { sponsorableLogins: [sponsorableLogin] },
+        )
+        return [sponsorableLogin, totalInCents] as const
+      }),
+    ),
+  )
+}
+
+function summarizeSponsoringRecords(records: GitHubSponsoringRecord[]) {
+  const [first, ...rest] = records
+  let latest = first
+  let firstCreatedAt = first.createdAt
+  let isOneTime = first.isOneTime
+  const raws = [first.raw]
+
+  for (const record of rest) {
+    raws.push(record.raw)
+    if (Date.parse(record.createdAt) > Date.parse(latest.createdAt))
+      latest = record
+    if (record.createdAt.localeCompare(firstCreatedAt) < 0)
+      firstCreatedAt = record.createdAt
+    isOneTime &&= record.isOneTime
+  }
+
+  return {
+    latest,
+    firstCreatedAt,
+    isOneTime,
+    raws,
+  }
+}
+
+export async function fetchGitHubSponsoring(
+  token: string,
+  login: string,
+  type: GitHubAccountType,
+  activeOnly = true,
+): Promise<GitHubSponsoringRecord[]> {
+  assertGitHubSponsoringParams(token, login, type)
+
+  return (await fetchGitHubSponsoringNodes(token, login, type, activeOnly))
+    .filter((raw: any) => !!raw.tier && !!raw.sponsorable)
+    .map(toGitHubSponsoringRecord)
+}
+
+export async function fetchGitHubSponsoringAsSponsorships(
+  token: string,
+  login: string,
+  type: GitHubAccountType,
+): Promise<Sponsorship[]> {
+  // Sponsees mode always loads full history regardless of active status.
+  const records = await fetchGitHubSponsoring(token, login, type, false)
+  const recordsBySponsorable = groupSponsoringRecordsByLogin(records)
+  const totalBySponsorable = await fetchTotalCentsBySponsorable(
+    token,
+    login,
+    type,
+    [...recordsBySponsorable.keys()],
+  )
+
+  return [...recordsBySponsorable.entries()].map(([sponsorableLogin, list]) => {
+    const summary = summarizeSponsoringRecords(list)
+    const totalInCents = totalBySponsorable.get(sponsorableLogin) || 0
+
+    return {
+      sponsor: {
+        type: summary.latest.sponsorable.type,
+        login: summary.latest.sponsorable.login,
+        name: summary.latest.sponsorable.name,
+        avatarUrl: summary.latest.sponsorable.avatarUrl,
+        websiteUrl: summary.latest.sponsorable.websiteUrl,
+        linkUrl: summary.latest.sponsorable.linkUrl,
+        socialLogins: {
+          github: summary.latest.sponsorable.login,
+        },
+      },
+      isOneTime: summary.isOneTime,
+      // In sponsees mode, ranking/tiers are based on lifetime sponsored amount.
+      monthlyDollars: totalInCents / 100,
+      privacyLevel: summary.latest.privacyLevel,
+      tierName: summary.latest.tierName,
+      createdAt: summary.firstCreatedAt,
+      raw: {
+        records: summary.raws,
+        totalSponsoredCents: totalInCents,
+      },
+    }
+  })
+}
+
+export async function fetchGitHubTotalSponsorshipAmountAsSponsor(
+  token: string,
+  login: string,
+  type: GitHubAccountType,
+  options: GitHubSponsoringTotalOptions = {},
+): Promise<number> {
+  assertGitHubSponsoringParams(token, login, type)
+
+  const query = makeSponsoringTotalAmountQuery(login, type, options)
+  const data = await requestGitHubSponsoringGraphQL(token, query)
+
+  const totalInCents = data.data?.[type]?.totalSponsorshipAmountAsSponsorInCents
+  if (typeof totalInCents !== 'number')
+    throw new Error('Invalid GitHub response: `totalSponsorshipAmountAsSponsorInCents` is missing')
+
+  return totalInCents
+}
+
+export function makeSponsoringQuery(
+  login: string,
+  type: GitHubAccountType,
+  activeOnly = true,
+  cursor?: string,
+) {
+  return graphql`{
+  ${type}(login: "${login}") {
+    sponsorshipsAsSponsor(activeOnly: ${Boolean(activeOnly)}, first: 100${cursor ? ` after: "${cursor}"` : ''}) {
+      totalCount
+      pageInfo {
+        endCursor
+        hasNextPage
+      }
+      nodes {
+        createdAt
+        privacyLevel
+        isActive
+        tier {
+          name
+          isOneTime
+          monthlyPriceInCents
+          monthlyPriceInDollars
+        }
+        sponsorable {
+          __typename
+          ...on Organization {
+            login
+            name
+            avatarUrl
+            websiteUrl
+          }
+          ...on User {
+            login
+            name
+            avatarUrl
+            websiteUrl
+          }
+        }
+      }
+    }
+  }
+}`
+}
+
+export function makeSponsoringTotalAmountQuery(
+  login: string,
+  type: GitHubAccountType,
+  options: GitHubSponsoringTotalOptions = {},
+) {
+  const args: string[] = []
+  if (options.since)
+    args.push(`since: ${JSON.stringify(options.since)}`)
+  if (options.until)
+    args.push(`until: ${JSON.stringify(options.until)}`)
+  if (options.sponsorableLogins?.length)
+    args.push(`sponsorableLogins: [${options.sponsorableLogins.map(v => JSON.stringify(v)).join(', ')}]`)
+
+  const parameters = args.length
+    ? `(${args.join(', ')})`
+    : ''
+
+  return graphql`{
+  ${type}(login: "${login}") {
+    totalSponsorshipAmountAsSponsorInCents${parameters}
+  }
+}`
+}