@profullstack/builtindie 0.1.3 → 0.6.0

package/src/service.ts

@@ -5,22 +5,27 @@
  *   submit   URL in, a listing out: everything fetched, pictures saved. Free.
  *            Anonymous launches go live at once; a signed-in submitter checks a draft first.
  *   publish  the draft goes live on today's board
- *   claim    the domain's owner proves it with a DNS TXT record and takes the listing
+ *   claim    the domain's owner proves it (a DNS TXT record, or the badge with their token) and takes the listing
  *   refetch  read the homepage again (the maker changed their logo)
  *   verify   the maker put our badge on their site: a followed link back
- *   feature  pay in crypto (CoinPay) to sit on top for a week
+ *   feature  pay on CoinPay's hosted checkout (any coin or PayPal) to sit on top for a week
+ *   vote, comment, review, share   what members do on a listing; each pays karma (karma.ts)
  *
  * Products are described in the LogicSRC open specs: each one is an OpenSite
  * record (logicsrc.com/docs/opensite) and an OpenProfile.md with Kind
  * organization (logicsrc.com/docs/openprofile); a maker is an OpenProfile.md
  * of their own, which we read and link to.
  */
-import { createHmac, timingSafeEqual } from 'node:crypto'
+import { createHmac, randomBytes } from 'node:crypto'
 import { Resolver } from 'node:dns/promises'
 import { keyedSection, listSection, makeOpenProfile, renderOpenProfile } from '@profullstack/openprofile'
 import { autofetch, clip, FetchError, normalizeUrl, readProfile, safeFetch, SOCIAL_KINDS, videoFrom, type FetchOptions, type SiteInfo, type Video } from './fetch.js'
 import { Media, screenshot } from './media.js'
-import { dayOf, makerIdFor, newId, Store, type Product, type User } from './db.js'
+import { dayOf, makerIdFor, newId, Store, type Comment, type Product, type Review, type User } from './db.js'
+import { Karma, SHARE_NETWORKS } from './karma.js'
+import { cleanTags } from './tags.js'
+import { validEmail } from './auth.js'
+import { CoinPay, CoinPayError, readWebhook, verifyWebhook } from '@profullstack/coinpay-onboard'
 
 export class InputError extends Error {
   constructor(message: string, readonly field?: string) {
@@ -28,50 +33,64 @@ export class InputError extends Error {
   }
 }
 
-export type CoinPayConfig = { baseUrl: string; apiKey: string; businessId: string; webhookSecret: string }
+export type CoinPayConfig = { baseUrl: string; apiKey: string; businessId: string; webhookSecret: string; /** Tests pass their own. */ fetch?: typeof fetch }
 export type Config = {
   origin: string
   coinpay: CoinPayConfig | null
   featureUsd: number
   featureDays: number
-  chains: string[]
   fetch?: FetchOptions
   screenshots?: boolean
   /** Secret behind each person's claim token. */
   claimSecret?: string
   /** TXT lookups; tests pass their own. */
   resolveTxt?: (name: string) => Promise<string[][]>
+  /** Karma per free Featured week (KARMA_PER_CREDIT, default 500). */
+  karmaPerCredit?: number
 }
 
 /** The record an owner adds: `_built-indie.<domain> TXT "built-indie-verify=<token>"` (or the same on the domain itself). */
 export const CLAIM_LABEL = '_built-indie'
 export const CLAIM_PREFIX = 'built-indie-verify='
 
-const resolver = new Resolver({ timeout: 4000, tries: 2 })
-resolver.setServers(['1.1.1.1', '9.9.9.9'])
-const publicTxt = (name: string) => resolver.resolveTxt(name)
-
-export const CHAIN_LABELS: Record<string, string> = {
-  USDC_POL: 'USDC on Polygon', USDC_SOL: 'USDC on Solana', USDC_ETH: 'USDC on Ethereum', USDT_POL: 'USDT on Polygon',
-  BTC: 'Bitcoin', ETH: 'Ether', SOL: 'Solana', POL: 'Polygon', DOGE: 'Dogecoin', BCH: 'Bitcoin Cash', XRP: 'XRP', ADA: 'Cardano', BNB: 'BNB',
+/**
+ * TXT records as public resolvers see them: every answer from 1.1.1.1 and 9.9.9.9, merged.
+ * One Resolver per server on purpose: Bun 1.4's node:dns Resolver given two servers
+ * answers ENOTFOUND for a record each of them serves alone, so no claim could succeed.
+ * And fresh Resolvers per lookup: a long-lived one caches NXDOMAIN for the zone's SOA
+ * minimum (often 30 min), so a maker who checks before adding the record stays refused.
+ */
+const publicDns = () =>
+  ['1.1.1.1', '9.9.9.9'].map((server) => {
+    const r = new Resolver({ timeout: 4000, tries: 2 })
+    r.setServers([server])
+    return r
+  })
+export async function publicTxt(name: string, resolvers: Pick<Resolver, 'resolveTxt'>[] = publicDns()): Promise<string[][]> {
+  const answers = await Promise.all(resolvers.map((r) => r.resolveTxt(name).catch(() => [] as string[][])))
+  return answers.flat()
 }
-export const DEFAULT_CHAINS = Object.keys(CHAIN_LABELS)
-export const SETTLED = new Set(['paid', 'completed', 'confirmed', 'forwarded', 'succeeded', 'settled'])
+
+/** Who is paying for a Featured slot: the email is required by CoinPay; the account is the member id, or the email for a guest. */
+export type Buyer = { email: string; accountId?: string | null }
 
 export type Edit = Partial<{ name: string; tagline: string; description: string; tags: string[] | string; makerName: string; makerProfile: string; videos: string[] | string; socials: Record<string, string>; remove: string[] | string }>
 
 const list = (v: string[] | string | undefined) => (Array.isArray(v) ? v : String(v ?? '').split(/[\n,]+/)).map((s) => s.trim()).filter(Boolean)
 
 export class BuiltIndie {
-  constructor(readonly store: Store, readonly media: Media, readonly config: Config) {}
+  readonly karma: Karma
+  constructor(readonly store: Store, readonly media: Media, readonly config: Config) {
+    this.karma = new Karma(store, config.karmaPerCredit ?? 500)
+  }
 
   /** A product page's public address. */
   link(p: Pick<Product, 'slug'>): string {
     return `${this.config.origin}/p/${p.slug}`
   }
 
-  /** Read the URL and make a draft. A URL already live comes back as `existing` instead. */
-  async submit(input: { url: string; makerName?: string; makerProfile?: string }, submitter: string, user: User | null = null): Promise<{ product: Product; existing: boolean }> {
+  /** Read the URL and make a draft. A URL already live comes back as `existing` instead. `unlimited` (the admin) skips the hourly cap. */
+  async submit(input: { url: string; makerName?: string; makerProfile?: string }, submitter: string, user: User | null = null, unlimited = false): Promise<{ product: Product; existing: boolean }> {
     let url: URL
     try {
       url = normalizeUrl(input.url)
@@ -80,7 +99,7 @@ export class BuiltIndie {
     }
     const already = this.store.byUrl(url.href)
     if (already?.status === 'live') return { product: already, existing: true }
-    if (this.store.submissionsFrom(submitter, Date.now() - 3600_000) >= 10) throw new InputError('That is a lot of launches in an hour. Try again later.')
+    if (!unlimited && this.store.submissionsFrom(submitter, Date.now() - 3600_000) >= 10) throw new InputError('That is a lot of launches in an hour. Try again later.')
     const info = await this.read(url.href)
     const id = newId()
     const pictures = await this.pictures(id, info)
@@ -118,22 +137,88 @@ export class BuiltIndie {
     return createHmac('sha256', this.config.claimSecret ?? 'built.indie').update(`claim:${user.id}:${p.domain}`).digest('base64url').slice(0, 24)
   }
 
-  /** Look for the claim record at _built-indie.<domain>, then on the domain itself (and its apex for www). */
-  async claim(p: Product, user: User): Promise<{ ok: boolean; looked: string[] }> {
+  /**
+   * Two proofs, either one claims it: the TXT record at _built-indie.<domain> (or on the
+   * domain itself, and its apex for www), or, failing DNS, our badge on the homepage
+   * carrying this person's badge id (`/images.svg?id=<id>`, the easy way). Kept for
+   * badges already placed: `/badge/<slug>.svg?claim=<token>`, or the bare
+   * `built-indie-verify=<token>` anywhere in the HTML, e.g. a meta tag. A badge that
+   * claims also earns the followed link and the ✓, as `verify` would.
+   */
+  async claim(p: Product, user: User): Promise<{ ok: boolean; looked: string[]; method?: 'dns' | 'badge' }> {
     if (p.status === 'hidden') throw new InputError('This product was taken down.')
     if (p.ownerId === user.id) return { ok: true, looked: [] }
-    const want = `${CLAIM_PREFIX}${this.claimToken(p, user)}`
+    const token = this.claimToken(p, user)
+    const want = `${CLAIM_PREFIX}${token}`
     const bare = p.domain.replace(/^www\./, '')
     const names = [...new Set([`${CLAIM_LABEL}.${bare}`, bare, p.domain])]
+    const looked = [...names, p.url]
     const lookup = this.config.resolveTxt ?? publicTxt
     for (const name of names) {
       const records = await lookup(name).catch(() => [] as string[][])
       if (records.some((chunks) => chunks.join('').trim() === want)) {
-        this.store.claim(p.id, user.id)
-        return { ok: true, looked: names }
+        this.claimed(p, user, false)
+        return { ok: true, looked, method: 'dns' }
       }
     }
-    return { ok: false, looked: names }
+    const html = await this.homepage(p)
+    const own = this.badgeIds(html).some((id) => {
+      const b = this.store.badge(id)
+      return b?.productId === p.id && b.userId === user.id
+    })
+    if (own) {
+      this.claimed(p, user, true)
+      return { ok: true, looked, method: 'badge' }
+    }
+    if (this.hasClaimBadge(html, token)) {
+      this.claimed(p, user, this.linksBack(html))
+      return { ok: true, looked, method: 'badge' }
+    }
+    return { ok: false, looked }
+  }
+
+  /** The claim took: ownership, karma for it, and for the badge when it was the proof. */
+  private claimed(p: Product, user: User, verified: boolean): void {
+    this.store.claim(p.id, user.id)
+    if (verified) this.store.setVerified(p.id, Date.now())
+    const now = this.store.product(p.id)!
+    if (now.status === 'live') this.karma.claimed(now, user.id)
+    if (verified && now.status === 'live') this.karma.badgeVerified(now)
+  }
+
+  /** The product's homepage HTML, read the safe way (no private addresses, robots honoured); '' if it will not load. */
+  private async homepage(p: Product): Promise<string> {
+    const r = await safeFetch(p.url, { ...this.config.fetch, accept: 'text/html' }).catch(() => null)
+    return r && r.status < 300 ? new TextDecoder().decode(r.body) : ''
+  }
+
+  private ourHosts(): string {
+    return `(?:${new URL(this.config.origin).hostname.replace(/\./g, '\\.')}|built\\.indie)`
+  }
+
+  /** A followed-link-worthy link back to us. */
+  private linksBack(html: string): boolean {
+    return new RegExp(`href=["']?https?://${this.ourHosts()}(/|["'])`, 'i').test(html)
+  }
+
+  /** Every link or image URL in the page that points at our host. */
+  private ourUrls(html: string): string[] {
+    if (!html) return []
+    return [...html.matchAll(new RegExp(`(?:href|src)\\s*=\\s*["']?((?:https?:)?//${this.ourHosts()}/[^"'\\s>]*)`, 'gi'))].map((m) => m[1]!)
+  }
+
+  /** The ids of every `/images.svg?id=<id>` badge on our host in the page. */
+  badgeIds(html: string): string[] {
+    const ids = this.ourUrls(html).map((u) => u.match(/\/images\.svg\?(?:[^#]*?(?:&|&amp;))?id=([A-Za-z0-9_-]+)/)?.[1])
+    return [...new Set(ids.filter((id): id is string => Boolean(id)))]
+  }
+
+  /** A link or image on our host whose URL carries claim=<token>, or the bare verify string anywhere. */
+  private hasClaimBadge(html: string, token: string): boolean {
+    if (!html) return false
+    const exact = (prefix: string) => new RegExp(`${prefix}${token}(?![A-Za-z0-9_-])`)
+    if (exact(CLAIM_PREFIX).test(html)) return true
+    return this.ourUrls(html).some((u) => exact('[?&](?:amp;)?claim=').test(u))
   }
 
   private async read(url: string): Promise<SiteInfo> {
@@ -164,7 +249,86 @@ export class BuiltIndie {
   publish(p: Product): Product {
     if (p.status === 'hidden') throw new InputError('This product was taken down.')
     if (!p.name.trim()) throw new InputError('Give it a name', 'name')
-    return this.store.update(p.id, { status: 'live' })!
+    const live = this.store.update(p.id, { status: 'live' })!
+    this.karma.launched(live)
+    // A claim made while it was a draft pays once it is live.
+    if (live.ownerId) this.karma.claimed(live, live.ownerId)
+    // An invited member's first live listing earns whoever invited them a free Featured week.
+    const inviter = p.submitterUser ? this.store.earnInvite(p.submitterUser, p.id) : null
+    if (inviter) {
+      this.karma.inviteConverted(inviter, p.id)
+      this.onInviteEarned?.(inviter, live)
+    }
+    return live
+  }
+
+  // What members do on a listing. Anyone may vote; comments and reviews need an account.
+
+  /** One vote per visitor (their address); a signed-in voter is noted and earns karma. True when it counted. */
+  vote(p: Product, voter: string, user: User | null = null): boolean {
+    if (p.status !== 'live') throw new InputError('Only a live listing takes votes.')
+    if (!this.store.vote(p.id, voter, Date.now(), user?.id ?? null)) return false
+    this.karma.voted(p, user?.id ?? null)
+    return true
+  }
+
+  comment(p: Product, user: User, text: string, parentId?: string | null): Comment {
+    if (p.status !== 'live') throw new InputError('Only a live listing takes comments.')
+    const body = String(text ?? '').replace(/\r\n?/g, '\n').replace(/\n{3,}/g, '\n\n').trim().slice(0, 2000)
+    if (body.length < 2) throw new InputError('Write something first.', 'body')
+    let parent: Comment | null = null
+    if (parentId) {
+      parent = this.store.comment(parentId)
+      if (!parent || parent.productId !== p.id || parent.deletedAt) throw new InputError('That comment is gone.', 'parent')
+      // One level of replies: answering a reply answers its thread.
+      if (parent.parentId) parent = this.store.comment(parent.parentId)
+    }
+    const c = this.store.addComment({ productId: p.id, userId: user.id, parentId: parent?.id ?? null, body })
+    this.karma.commented(p, user.id, c)
+    return c
+  }
+
+  /** Delete a comment: its author, or the admin. Takes back the karma it earned. */
+  deleteComment(id: string, user: User | null, admin = false): Comment {
+    const c = this.store.comment(id)
+    if (!c || c.deletedAt) throw new InputError('No such comment.')
+    if (!admin && c.userId !== user?.id) throw new InputError('Only its author can delete a comment.')
+    this.store.deleteComment(id)
+    this.karma.uncommented(id)
+    return c
+  }
+
+  review(p: Product, user: User, rating: unknown, text: unknown): Review {
+    if (p.status !== 'live') throw new InputError('Only a live listing takes reviews.')
+    const stars = Number(rating)
+    if (!Number.isInteger(stars) || stars < 1 || stars > 5) throw new InputError('Pick 1 to 5 stars.', 'rating')
+    const body = String(text ?? '').replace(/\r\n?/g, '\n').trim().slice(0, 2000)
+    const r = this.store.putReview({ productId: p.id, userId: user.id, rating: stars, body })
+    this.karma.reviewed(p, user.id, r)
+    return r
+  }
+
+  deleteReview(p: Product, userId: string): boolean {
+    const gone = this.store.deleteReview(p.id, userId)
+    if (gone) this.karma.unreviewed(p, userId)
+    return gone
+  }
+
+  /** A share button clicked. Pays a signed-in member (once per listing, network and day). */
+  share(p: Product, user: User | null, network: string): { counted: boolean } {
+    if (p.status !== 'live') throw new InputError('Only a live listing can be shared.')
+    if (!(SHARE_NETWORKS as readonly string[]).includes(network)) throw new InputError(`network is one of ${SHARE_NETWORKS.join(', ')}`, 'network')
+    return { counted: this.karma.shared(p, user?.id ?? null, network) }
+  }
+
+  /** Called when a listing earns its submitter's inviter a credit: the server mails them and refreshes the board. */
+  onInviteEarned?: (inviterId: string, product: Product) => void
+
+  /** Spend one invite credit on a live listing: featured for the usual number of days, free. */
+  redeemCredit(p: Product, user: User): Product {
+    if (p.status !== 'live') throw new InputError('Only a live listing can be featured.')
+    if (!this.store.redeemCredit(user.id, p.id, this.config.featureDays)) throw new InputError('No invite credits left. Invite a maker who launches to earn one.')
+    return this.store.product(p.id)!
   }
 
   async refetch(p: Product): Promise<Product> {
@@ -182,7 +346,7 @@ export class BuiltIndie {
     }
     if (e.tagline !== undefined) patch.tagline = clip(e.tagline, 90)
     if (e.description !== undefined) patch.description = clip(e.description, 1200)
-    if (e.tags !== undefined) patch.tags = [...new Set(list(e.tags).map((t) => t.toLowerCase().replace(/^#/, '').replace(/[^a-z0-9 +#.-]/g, '').slice(0, 24)).filter((t) => t.length >= 2))].slice(0, 6)
+    if (e.tags !== undefined) patch.tags = cleanTags(list(e.tags))
     if (e.makerName !== undefined) patch.makerName = clip(e.makerName, 60)
     if (e.videos !== undefined) {
       const videos: Video[] = []
@@ -238,13 +402,12 @@ export class BuiltIndie {
     return this.store.update(p.id, { makerProfile: r.url.href, makerId: maker.id, makerVerified: verified, makerName: clip(name?.trim() || profile.name, 60) })!
   }
 
-  /** Has the maker linked back to us from their homepage? */
+  /** Has the maker linked back to us from their homepage, or put this listing's badge (any account's id) on it? */
   async verify(p: Product): Promise<boolean> {
-    const r = await safeFetch(p.url, { ...this.config.fetch, accept: 'text/html' }).catch(() => null)
-    const html = r && r.status < 300 ? new TextDecoder().decode(r.body) : ''
-    const ours = new URL(this.config.origin).hostname
-    const ok = new RegExp(`href=["']?https?://(${ours.replace(/\./g, '\\.')}|built\\.indie)(/|["'])`, 'i').test(html)
+    const html = await this.homepage(p)
+    const ok = this.linksBack(html) || this.badgeIds(html).some((id) => this.store.badge(id)?.productId === p.id)
     this.store.setVerified(p.id, ok ? Date.now() : null)
+    if (ok && p.status === 'live') this.karma.badgeVerified(p)
     return ok
   }
 
@@ -308,61 +471,73 @@ export class BuiltIndie {
     )
   }
 
-  /** Start a crypto payment to feature a product; returns where to send the buyer. */
-  async feature(p: Product, chain: string, fetcher: typeof fetch = fetch): Promise<{ checkoutUrl: string; ref: string }> {
+  /**
+   * Start a CoinPay hosted checkout session to feature a product; returns where to send
+   * the buyer. The buyer picks any coin or PayPal on CoinPay's page, so there is no
+   * currency picker here.
+   */
+  async feature(p: Product, buyer: Buyer): Promise<{ checkoutUrl: string; ref: string; sessionId: string; methods: string[] }> {
     const cp = this.config.coinpay
     if (!cp) throw new InputError('Featuring is not set up on this server yet.')
     if (p.status !== 'live') throw new InputError('Publish it first.')
-    if (!this.config.chains.includes(chain)) throw new InputError('Pick a currency from the list', 'chain')
-    const res = await fetcher(`${cp.baseUrl}/api/payments/create`, {
-      method: 'POST',
-      headers: { authorization: `Bearer ${cp.apiKey}`, 'content-type': 'application/json' },
-      body: JSON.stringify({
-        business_id: cp.businessId,
+    const email = validEmail(buyer.email)
+    if (!email) throw new InputError('Enter your email: CoinPay sends the receipt there', 'email')
+    const accountId = String(buyer.accountId ?? '').trim() || email
+    const ref = `fp_${randomBytes(9).toString('base64url')}`
+    const link = this.link(p)
+    const client = new CoinPay({ token: cp.apiKey, base: cp.baseUrl, fetch: cp.fetch ?? fetch })
+    let session
+    try {
+      session = await client.createCheckoutSession({
         amount: this.config.featureUsd,
         currency: 'USD',
-        blockchain: chain,
-        payment_method: 'crypto',
         description: `built.indie: feature ${p.name} for ${this.config.featureDays} days`,
-        metadata: { product_id: p.id, product: 'feature' },
-        success_url: `${this.link(p)}?featured=1`,
-        cancel_url: this.link(p),
-      }),
-      signal: AbortSignal.timeout(20_000),
-    })
-    if (!res.ok) throw new Error(`CoinPay said ${res.status}: ${(await res.text()).slice(0, 200)}`)
-    const body = (await res.json()) as any
-    const payment = body?.payment ?? body
-    const ref = String(payment?.id ?? payment?.payment_id ?? '')
-    if (!ref) throw new Error('CoinPay returned no payment reference')
+        customerEmail: email,
+        accountId,
+        property: new URL(this.config.origin || 'https://built.indie.pit.world').hostname,
+        metadata: { product_id: p.id, product: 'feature', days: this.config.featureDays, payment_ref: ref },
+        successUrl: `${link}?featured=1`,
+        cancelUrl: link,
+        expiresInMinutes: 60,
+      })
+    } catch (e) {
+      throw new Error(`CoinPay said ${e instanceof CoinPayError ? e.status : 'error'}: ${(e as Error).message.slice(0, 200)}`)
+    }
+    if (!session?.id || !session.url) throw new Error('CoinPay returned no checkout session')
     // Written before the buyer leaves: a webhook can beat the redirect.
-    this.store.addPayment({ ref, productId: p.id, amountUsd: this.config.featureUsd, chain, days: this.config.featureDays })
-    return { checkoutUrl: `${cp.baseUrl}/pay/${ref}`, ref }
+    this.store.addPayment({ ref, productId: p.id, amountUsd: this.config.featureUsd, chain: 'checkout', days: this.config.featureDays, checkoutSessionId: session.id, email, accountId })
+    return { checkoutUrl: session.url, ref, sessionId: session.id, methods: session.methods ?? [] }
   }
 
-  /** CoinPay's webhook: `t=<unix>,v1=<hmac of "t.body">`; the payload is { data: { payment_id, status } }. */
-  webhook(raw: string, header: string | undefined, nowSeconds = Date.now() / 1000): { ok: boolean; status?: number } {
+  /**
+   * CoinPay's webhook: `X-CoinPay-Signature: t=<unix>,v1=<hmac of "t.body">` over the raw
+   * bytes; the body is nested, `{ id: evt_..., type, data: { payment_id, status,
+   * checkout_session_id, metadata } }`. Paid = payment.confirmed (a PayPal capture has
+   * status 'completed') or payment.forwarded; one session can send both, so settling is
+   * once per local payment.
+   */
+  webhook(raw: string, header: string | undefined, nowSeconds = Date.now() / 1000): { ok: boolean; status?: number; settled?: boolean } {
     const cp = this.config.coinpay
     if (!cp?.webhookSecret || !header) return { ok: false, status: 401 }
-    const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=').map((s) => s.trim())))
-    const t = Number(parts.t)
-    if (!Number.isFinite(t) || !parts.v1 || Math.abs(nowSeconds - t) > 300) return { ok: false, status: 401 }
-    const expected = Buffer.from(createHmac('sha256', cp.webhookSecret).update(`${parts.t}.${raw}`).digest('hex'), 'hex')
-    const given = Buffer.from(String(parts.v1), 'hex')
-    if (expected.length !== given.length || !timingSafeEqual(expected, given)) return { ok: false, status: 401 }
-    let payload: any
+    if (!verifyWebhook(raw, header, cp.webhookSecret, nowSeconds * 1000)) return { ok: false, status: 401 }
+    let payload: unknown
     try {
       payload = JSON.parse(raw)
     } catch {
       return { ok: false, status: 400 }
     }
-    const data = payload?.data ?? payload
-    const ref = String(data?.payment_id ?? data?.id ?? '')
-    const status = String(data?.status ?? payload?.type?.replace(/^payment\./, '') ?? '').toLowerCase()
-    if (!ref || !this.store.payment(ref)) return { ok: true }
-    if (SETTLED.has(status)) this.store.settle(ref)
-    else if (status) this.store.setPaymentStatus(ref, status)
-    return { ok: true }
+    const ev = readWebhook(payload)
+    const row =
+      (ev.checkoutSessionId && this.store.paymentBySession(ev.checkoutSessionId)) ||
+      (typeof ev.metadata.payment_ref === 'string' && this.store.payment(ev.metadata.payment_ref)) ||
+      (ev.paymentId && this.store.payment(ev.paymentId)) ||
+      null
+    if (!row) return { ok: true }
+    if (ev.paymentId) this.store.notePaymentId(row.ref, ev.paymentId, ev.method || null)
+    if (ev.paid) return { ok: true, settled: this.store.settle(row.ref) }
+    const status = ev.status || ev.type.replace(/^payment\./, '')
+    if (status) this.store.setPaymentStatus(row.ref, status)
+    return { ok: true, settled: false }
   }
 }
 

package/src/tags.ts

@@ -0,0 +1,92 @@
+/**
+ * Tags: one shape for every tag, and topics inferred from a listing's own words
+ * when its homepage declares none (no keywords meta, JSON-LD category or
+ * opensite.json tags). Inference is a fixed vocabulary, so it is cheap,
+ * offline and the same on every run.
+ */
+
+export const MAX_TAGS = 6
+
+/** Lower case, no leading #, only a-z 0-9 space + # . -, 2 to 24 characters; null if nothing is left. */
+export function normalizeTag(raw: string): string | null {
+  const t = String(raw)
+    .toLowerCase()
+    .replace(/^#/, '')
+    .replace(/application$/, '')
+    .replace(/[^a-z0-9 +#.-]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return t.length >= 2 && t.length <= 24 ? t : null
+}
+
+/** Normalized, unique, at most `max`. */
+export function cleanTags(raw: Iterable<string>, max = MAX_TAGS): string[] {
+  const out = new Set<string>()
+  for (const r of raw) {
+    const t = normalizeTag(r)
+    if (t) out.add(t)
+    if (out.size >= max) break
+  }
+  return [...out]
+}
+
+/** Topic, and the words that mean it. Earlier topics win a tie. */
+const TOPICS: [string, RegExp][] = [
+  ['ai', /\b(ai|llms?|gpt|claude|codex|opencode|agentic|ai agents?|open models?|whisper(\.cpp)?)\b/g],
+  ['agents', /\b(agents?|agentic)\b/g],
+  ['developer tools', /\b(developers?|cli|apis?|sdk|codebase|coding|git|webhooks?|npm|registry|registries|ci\/?cd)\b/g],
+  ['game', /\b(games?|gaming|gamers?|play|shooter|multiplayer|co-op|campaign)\b/g],
+  ['tactical', /\b(operatives?|tactical|combat|military|war)\b/g],
+  ['sports', /\b(sports?|youth-sports|athletes?|league|fixtures|teams? in the world)\b/g],
+  ['crypto', /\b(crypto|bitcoin|btc|eth|usdc|sol|stablecoins?|lightning|web3|wallets?|coinpay)\b/g],
+  ['payments', /\b(payments?|checkout|pay link|get paid|pays you|invoices?|billing|pay by the)\b/g],
+  ['sms', /\b(sms|texts?|texting|phone numbers?|sim( cards?)?|carrier)\b/g],
+  ['verification', /\b(otp|2fa|verification( codes?)?|one-time codes?)\b/g],
+  ['email', /\b(e-?mail|newsletters?|inbox)\b/g],
+  ['voice', /\b(voice|calls?|dials?|phone tree|on hold)\b/g],
+  ['customer support', /\b(customer support|phone tree|helpdesk|support tickets?)\b/g],
+  ['video', /\b(videos?|reels?|films?|demo video|highlight)\b/g],
+  ['tv', /\b(iptv|tv( guide)?|live-tv|channels?|m3u|xtream)\b/g],
+  ['music', /\b(music|spotify|albums?|songs?|genres?)\b/g],
+  ['audio', /\b(audio|podcasts?|recordings?|transcripts?|transcri\w+)\b/g],
+  ['news', /\b(news|newsrooms?|headlines|journalism|the desk)\b/g],
+  ['alerts', /\b(reminders?|alerts?|notifications?|get told|never miss|before it drops)\b/g],
+  ['jobs', /\b(jobs?|hiring|freelanc\w*|gigs?|careers?)\b/g],
+  ['health', /\b(health|telehealth|medical|patients?|clinics?|prescriptions?|labs)\b/g],
+  ['food', /\b(recipes?|cookbooks?|food|cooking|ingredients)\b/g],
+  ['cannabis', /\b(cannabis|dispensar(y|ies)|weed)\b/g],
+  ['directory', /\b(directory|directories|listings?|search engine|compared)\b/g],
+  ['data', /\b(database|datasets?|structured data|feeds?|json|real-time public data)\b/g],
+  ['marketing', /\b(ads|advertis\w*|promot\w*|seo|marketing|launch sites|submissions?)\b/g],
+  ['automation', /\b(automat\w*|workflows?|deterministic)\b/g],
+  ['open source', /\b(open-source|open source|foss|self-host\w*)\b/g],
+  ['security', /\b(security|malware|encrypt\w*|vulnerab\w*|privacy|audit)\b/g],
+  ['photos', /\b(photos?|images?|pictures?|backgrounds?|camera)\b/g],
+  ['terminal', /\b(terminal|ssh|tmux|bbs|bulletin board)\b/g],
+  ['no-code', /\b(no-code|your own words|describe what you want)\b/g],
+  ['open standards', /\b(standards|schemas?|specs?|conventions|primitives)\b/g],
+  ['shopping', /\b(shop|buy|marketplace|e-?commerce|store)\b/g],
+  ['art', /\b(tattoos?|artistry|artist)\b/g],
+  ['automotive', /\b(auto detailing|cars?|automotive)\b/g],
+  ['cigars', /\b(cigars?|spliffs?|tobacco)\b/g],
+  ['events', /\b(events?|meetups?|herf|every other sunday)\b/g],
+  ['productivity', /\b(productivity|organi[sz]e|searchable|right folder)\b/g],
+]
+
+/** Up to `max` topics the text is about, most mentioned first. */
+export function inferTags(text: string, max = 4): string[] {
+  const t = ` ${text.toLowerCase()} `
+  return TOPICS.map(([tag, re], i) => ({ tag, i, n: t.match(re)?.length ?? 0 }))
+    .filter((s) => s.n > 0)
+    // "never miss a game" is a match, not a video game.
+    .filter((s, _, all) => s.tag !== 'game' || !all.some((o) => o.tag === 'sports'))
+    .sort((a, b) => b.n - a.n || a.i - b.i)
+    .slice(0, max)
+    .map((s) => s.tag)
+}
+
+/** What a listing is tagged with: its declared tags, else topics from its name, tagline and description. */
+export function tagsFor(declared: string[], text: { name?: string; tagline?: string; description?: string }): string[] {
+  const own = cleanTags(declared)
+  return own.length ? own : inferTags([text.name, text.tagline, text.description].filter(Boolean).join('. '))
+}

package/src/tui.ts

@@ -2,13 +2,13 @@
  * `builtindie` with no arguments: the board in the terminal.
  *
  * ←/→ switch board (today, week, month, all, new), ↑/↓ pick, Enter shows it,
- * v upvotes, l launches a URL you type, q quits. Glyphs come from the OpenIcon
+ * v upvotes, l launches a URL you type, k shows the karma leaderboard, q quits. Glyphs come from the OpenIcon
  * set: Nerd Font, Unicode or ASCII, whichever this terminal can draw.
  */
 const UP = glyph('arrow-up') || '^'
 const OK = glyph('check') || '+'
 import { createApp } from '@profullstack/hqtui'
-import { BuiltIndieClient, type ApiProduct } from './client.js'
+import { BuiltIndieClient, type ApiProduct, type BoardRows } from './client.js'
 import { glyph } from './icons.js'
 
 export const WINDOWS = ['today', 'week', 'month', 'all', 'new'] as const
@@ -21,12 +21,14 @@ export type TuiState = {
   typing: string | null
   busy: string | null
   flash: string | null
+  /** The karma leaderboard, while it is open (k). */
+  board: BoardRows | null
 }
 
-export const initialState = (): TuiState => ({ window: 0, products: [], at: 0, open: null, typing: null, busy: null, flash: null })
+export const initialState = (): TuiState => ({ window: 0, products: [], at: 0, open: null, typing: null, busy: null, flash: null, board: null })
 
 /** Pure key handling, testable without a terminal. */
-export function onKey(s: TuiState, key: { name: string; key: string; char?: string }): 'load' | 'vote' | 'launch' | 'quit' | null {
+export function onKey(s: TuiState, key: { name: string; key: string; char?: string }): 'load' | 'vote' | 'launch' | 'karma' | 'quit' | null {
   if (key.key === 'ctrl+c') return 'quit'
   if (s.typing !== null) {
     if (key.name === 'escape') s.typing = null
@@ -35,8 +37,14 @@ export function onKey(s: TuiState, key: { name: string; key: string; char?: stri
     else if (key.char && key.char.length === 1 && !key.key.startsWith('ctrl+')) s.typing += key.char
     return null
   }
+  if (s.board) {
+    if (key.name === 'escape' || key.char === 'k') s.board = null
+    else if (key.char === 'q') return 'quit'
+    return null
+  }
   if (key.name === 'escape') return s.open ? ((s.open = null), null) : 'quit'
   if (key.char === 'q') return 'quit'
+  if (key.char === 'k') return 'karma'
   if (key.char === 'l') return (s.typing = ''), null
   if (key.char === 'v') return s.products[s.at] ? 'vote' : null
   if (key.name === 'right' || key.name === 'left') {
@@ -72,6 +80,12 @@ export async function runTui(client = new BuiltIndieClient()): Promise<void> {
     const action = onKey(s, event)
     if (action === 'quit') app.quit()
     else if (action === 'load') void load()
+    else if (action === 'karma') {
+      void run('Loading the karma board…', async () => {
+        const week = await client.leaderboard('karma', 'week', 25)
+        s.board = week.rows.length ? week : await client.leaderboard('karma', 'all', 25)
+      })
+    }
     else if (action === 'vote') {
       const p = s.products[s.at]!
       void run('Voting…', async () => {
@@ -98,7 +112,14 @@ export async function runTui(client = new BuiltIndieClient()): Promise<void> {
       h.text(WINDOWS.map((w, i) => (i === s.window ? `[${w}]` : w)).join('  '), { fg: theme.text })
       h.text(`${client.base.replace(/^https?:\/\//, '')} `, { fg: theme.muted, align: 'right' })
     })
-    if (s.open) {
+    if (s.board) {
+      const r = s.board
+      ui.panel({ title: `Top karma (${r.period === 'all' ? 'all time' : 'this week'})` }, (b: any) => {
+        if (!r.rows.length) b.text('Nobody yet. Sign in at built.indie, then upvote, review, comment and share to earn karma.', { fg: theme.muted })
+        for (const x of r.rows) b.text(`${String(x.rank ?? '').padStart(3)}. ${String(x.value).padStart(5)}  ${x.name} ${x.badges.map((g) => g.emoji).join('')}`, { fg: x.rank === 1 ? theme.accent : theme.text, bold: x.rank === 1 })
+        b.text(r.web, { fg: theme.muted })
+      })
+    } else if (s.open) {
       const p = s.open
       ui.panel({ title: `${p.name}  ${UP} ${p.votes}` }, (b: any) => {
         b.text(p.tagline, { fg: theme.accent, bold: true })
@@ -108,6 +129,7 @@ export async function runTui(client = new BuiltIndieClient()): Promise<void> {
         if (p.tags.length) b.text(`tags   ${p.tags.join(', ')}`, { fg: theme.muted })
         if (p.videos.length) b.text(`video  ${p.videos[0]!.url}`, { fg: theme.muted })
         if (p.maker) b.text(`maker  ${p.maker.name}${p.maker.verified ? ' ✓' : ''}`, { fg: theme.muted })
+        if (p.rating != null) b.text(`rated  ★ ${p.rating} from ${p.reviews}`, { fg: theme.muted })
       })
     } else {
       ui.panel({ title: s.busy ?? `${WINDOWS[s.window]} (${s.products.length})` }, (b: any) => {
@@ -120,7 +142,7 @@ export async function runTui(client = new BuiltIndieClient()): Promise<void> {
     }
     if (s.typing !== null) ui.panel({ title: 'Launch a URL', size: 3 }, (b: any) => b.text(`${s.typing}▏`, { fg: theme.accent }))
     else if (s.flash) ui.panel({ title: 'built.indie', size: 3 }, (b: any) => b.text(s.flash, { fg: theme.accent }))
-    ui.statusBar({ items: s.typing !== null ? [{ key: 'Enter', label: 'launch' }, { key: 'Esc', label: 'cancel' }] : [{ key: '←→', label: 'board' }, { key: '↑↓', label: 'pick' }, { key: 'Enter', label: 'open' }, { key: 'v', label: 'upvote' }, { key: 'l', label: 'launch' }, { key: 'q', label: 'quit' }], right: [{ label: 'built.indie' }] })
+    ui.statusBar({ items: s.typing !== null ? [{ key: 'Enter', label: 'launch' }, { key: 'Esc', label: 'cancel' }] : [{ key: '←→', label: 'board' }, { key: '↑↓', label: 'pick' }, { key: 'Enter', label: 'open' }, { key: 'v', label: 'upvote' }, { key: 'l', label: 'launch' }, { key: 'k', label: 'karma' }, { key: 'q', label: 'quit' }], right: [{ label: 'built.indie' }] })
   })
   void load()
   await app.start()

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.1.3'
+export const VERSION = '0.6.0'