@profullstack/builtindie 0.1.4 → 0.7.1

package/src/browse.ts

@@ -0,0 +1,243 @@
+/**
+ * Browse and search: one query over every live launch, with facets.
+ *
+ * A launch's tags are whatever its page or its maker said (often nothing), so
+ * we also file each one under a fixed set of categories, read from its tags,
+ * name, tagline and description. Every listing lands somewhere, and the same
+ * twenty words mean the same thing everywhere.
+ *
+ * Facets work the usual way: values within a facet are OR'd, facets are AND'd,
+ * and each facet counts what you would get by changing only that facet.
+ */
+import type { Product } from './db.js'
+
+export type Category = { key: string; label: string; words: string[] }
+
+export const CATEGORIES: Category[] = [
+  { key: 'developer-tools', label: 'Developer tools', words: ['developer', 'developers', 'devtools', 'dev tools', 'api', 'sdk', 'cli', 'code', 'coding', 'github', 'npm', 'open source', 'programming', 'terminal', 'mcp', 'cicd', 'ci/cd', 'git'] },
+  { key: 'ai', label: 'AI', words: ['ai', 'llm', 'llms', 'gpt', 'agent', 'agents', 'agentic', 'machine learning', 'artificial intelligence', 'chatbot', 'claude', 'openai', 'inference', 'gpu'] },
+  { key: 'crypto', label: 'Crypto & web3', words: ['crypto', 'cryptocurrency', 'bitcoin', 'blockchain', 'web3', 'usdc', 'ethereum', 'solana', 'defi', 'nft', 'multisig', 'escrow', 'stablecoin'] },
+  { key: 'finance', label: 'Finance & payments', words: ['finance', 'payment', 'payments', 'invoice', 'invoicing', 'billing', 'bank', 'banking', 'money', 'tax', 'taxes', 'accounting', 'stocks', 'trading', 'invest', 'investing', 'payment gateway'] },
+  { key: 'security', label: 'Security & privacy', words: ['security', 'cybersecurity', 'malware', 'vulnerability', 'vulnerabilities', 'threat', 'threats', 'privacy', 'encryption', 'encrypted', 'scanner', 'intrusion', 'firewall', 'vpn', 'backdoor', 'exposure management'] },
+  { key: 'productivity', label: 'Productivity', words: ['productivity', 'utilities', 'utility', 'workflow', 'automation', 'automate', 'notes', 'calendar', 'todo', 'bookmarks', 'sync', 'pdf'] },
+  { key: 'marketing', label: 'Marketing & SEO', words: ['marketing', 'seo', 'newsletter', 'newsletters', 'social media', 'ads', 'advertising', 'outreach', 'growth', 'analytics', 'leads', 'programmatic seo', 'affiliate', 'webring'] },
+  { key: 'media', label: 'Video & streaming', words: ['entertainment', 'movies', 'movie', 'video', 'videos', 'streaming', 'tv', 'iptv', 'torrent', 'torrents', 'film', 'films', 'youtube', 'ebooks', 'podcast', 'podcasts'] },
+  { key: 'music', label: 'Music & audio', words: ['music', 'audio', 'songs', 'radio', 'playlist', 'playlists', 'genre', 'genres', 'bands', 'concerts'] },
+  { key: 'news', label: 'News & publishing', words: ['news', 'blog', 'blogs', 'blogging', 'rss', 'feeds', 'journalism', 'publishing', 'magazine', 'content automation'] },
+  { key: 'education', label: 'Education', words: ['education', 'learn', 'learning', 'course', 'courses', 'training', 'tutorial', 'tutorials', 'school', 'students', 'kids'] },
+  { key: 'business', label: 'Business & SaaS', words: ['business', 'saas', 'b2b', 'crm', 'startup', 'startups', 'enterprise', 'small business', 'compliance', 'license', 'government'] },
+  { key: 'jobs', label: 'Jobs & freelance', words: ['jobs', 'job', 'hiring', 'freelance', 'freelancers', 'gig', 'gig economy', 'remote work', 'career', 'resume', 'recruiting'] },
+  { key: 'shopping', label: 'Shopping & deals', words: ['shopping', 'coupons', 'coupon', 'deals', 'discounts', 'promo codes', 'ecommerce', 'e-commerce', 'savings', 'marketplace'] },
+  { key: 'social', label: 'Social & community', words: ['social', 'community', 'communities', 'chat', 'forum', 'forums', 'messaging', 'messenger', 'dating', 'friends', 'sms'] },
+  { key: 'games', label: 'Games', words: ['game', 'games', 'gaming', 'esports', 'puzzle', 'play both sides', 'rpg', 'operatives', 'multiplayer', 'arcade'] },
+  { key: 'sports', label: 'Sports', words: ['sports', 'sport', 'youth-sports', 'athlete', 'athletes', 'league', 'leagues', 'nba', 'nfl', 'mlb', 'nhl', 'soccer', 'football', 'basketball', 'baseball', 'hockey', 'highlight reel', 'highlights', 'fixtures'] },
+  { key: 'design', label: 'Design & images', words: ['design', 'designer', 'image', 'images', 'photo', 'photos', 'background', 'backgrounds', 'icons', 'logo', 'logos', 'graphics', 'illustration', 'art', 'tattoo'] },
+  { key: 'lifestyle', label: 'Lifestyle & health', words: ['lifestyle', 'health', 'fitness', 'food', 'recipe', 'recipes', 'travel', 'family', 'ancestry', 'genealogy', 'home', 'pets', 'cannabis', 'weed', 'delivery', 'cigars', 'cigar', 'tattoo', 'detailing', 'bbq'] },
+  { key: 'data', label: 'Data & directories', words: ['directory', 'directories', 'dataset', 'datasets', 'database', 'databases', 'search engine', 'listings', 'index', 'scraper', 'lookup'] },
+  { key: 'hosting', label: 'Hosting & infrastructure', words: ['hosting', 'server', 'servers', 'vps', 'dns', 'domains', 'domain names', 'cloud', 'seedbox', 'bare metal', 'cdn', 'deploy', 'deployment', 'infrastructure'] },
+]
+const OTHER: Category = { key: 'other', label: 'Other', words: [] }
+export const CATEGORY_LABELS: Record<string, string> = Object.fromEntries([...CATEGORIES, OTHER].map((c) => [c.key, c.label]))
+
+const escRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+const MATCHERS = CATEGORIES.map((c) => ({ key: c.key, re: new RegExp(`(?:^|[^a-z0-9])(?:${c.words.map(escRe).join('|')})(?=$|[^a-z0-9])`, 'g') }))
+
+/**
+ * Up to three categories for a launch, best first. Tags and the tagline say
+ * what it is; the description only breaks ties, so a passing mention of
+ * "payments" in a long paragraph does not file a music site under finance.
+ */
+export function categorize(p: Pick<Product, 'tags' | 'name' | 'tagline' | 'description'>): string[] {
+  const strong = ` ${[...p.tags, p.name, p.tagline].join(' · ').toLowerCase()} `
+  const weak = ` ${p.description.toLowerCase()} `
+  const scored = MATCHERS.map((m) => ({ key: m.key, score: 3 * (strong.match(m.re)?.length ?? 0) + Math.min(2, weak.match(m.re)?.length ?? 0) }))
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+  // A lone weak hit is noise unless it is all we have.
+  const keep = scored.filter((s, i) => i === 0 || s.score >= 2).slice(0, 3)
+  return keep.length ? keep.map((s) => s.key) : [OTHER.key]
+}
+
+/** Things a launch has, each one a filter. */
+export const HAS: Record<string, { label: string; test: (p: Product, now: number) => boolean }> = {
+  verified: { label: '✓ Links back (verified)', test: (p) => Boolean(p.verifiedAt) },
+  claimed: { label: 'Claimed by its owner', test: (p) => Boolean(p.ownerId) },
+  featured: { label: '★ Featured now', test: (p, now) => Boolean(p.featuredUntil && p.featuredUntil > now) },
+  video: { label: 'Has a video', test: (p) => p.videos.length > 0 },
+  screenshots: { label: 'Has screenshots', test: (p) => Boolean(p.screenshot || p.images.length) },
+  llms: { label: 'llms.txt', test: (p) => Boolean(p.llms) },
+  opensite: { label: 'OpenSite', test: (p) => p.record?.source === 'declared' },
+  openprofile: { label: 'OpenProfile', test: (p) => Boolean(p.profile) },
+  openstack: { label: 'OpenStack (built with)', test: (p) => Boolean(p.extras.stack) },
+  opensaas: { label: 'OpenSaaS (pricing)', test: (p) => Boolean(p.extras.pricing) },
+  maker: { label: 'Names its maker', test: (p) => Boolean(p.makerName || p.makerId) },
+}
+
+const DAY = 86400_000
+export const LAUNCHED: Record<string, { label: string; ms: number }> = {
+  today: { label: 'Last 24 hours', ms: DAY },
+  week: { label: 'Past week', ms: 7 * DAY },
+  month: { label: 'Past month', ms: 30 * DAY },
+  year: { label: 'Past year', ms: 365 * DAY },
+}
+
+export const SORTS = { relevance: 'Best match', top: 'Most upvoted', new: 'Newest', name: 'Name A–Z' } as const
+export type Sort = keyof typeof SORTS
+
+export type Query = { q: string; category: string[]; tag: string[]; stack: string[]; has: string[]; maker: string[]; launched: string | null; sort: Sort; page: number }
+export type FacetName = 'category' | 'tag' | 'stack' | 'has' | 'maker' | 'launched'
+export type FacetValue = { value: string; label: string; count: number }
+export type Facets = Record<FacetName, FacetValue[]>
+export type Chip = { facet: FacetName | 'q'; value: string; label: string }
+export type Result = { query: Query; total: number; products: Product[]; facets: Facets; chips: Chip[]; categories: Map<string, string[]>; limit: number }
+
+/** The order facets appear in, with their headings. */
+export const FACETS: { name: FacetName; label: string; multi: boolean; top?: number }[] = [
+  { name: 'category', label: 'Category', multi: true },
+  { name: 'tag', label: 'Tags', multi: true, top: 30 },
+  { name: 'launched', label: 'Launched', multi: false },
+  { name: 'has', label: 'Has', multi: true },
+  { name: 'stack', label: 'Built with', multi: true, top: 20 },
+  { name: 'maker', label: 'Maker', multi: true, top: 20 },
+]
+
+const clean = (v: string, max = 60) => v.trim().slice(0, max)
+const listOf = (p: URLSearchParams, k: string, split: boolean) =>
+  [...new Set(p.getAll(k).flatMap((v) => (split ? v.split(',') : [v])).map((v) => clean(v)).filter(Boolean))].slice(0, 20)
+
+/** A query from a URL's parameters (pages and the API take the same ones). */
+export function parseQuery(params: URLSearchParams | Record<string, string | string[] | undefined>): Query {
+  const p = params instanceof URLSearchParams ? params : new URLSearchParams(Object.entries(params).flatMap(([k, v]) => (v === undefined ? [] : (Array.isArray(v) ? v : [v]).map((x) => [k, String(x)]))))
+  const q = clean(p.get('q') ?? '', 80)
+  const sort = (p.get('sort') ?? '') as Sort
+  const launched = p.get('launched') ?? ''
+  return {
+    q,
+    category: listOf(p, 'category', true).filter((c) => c in CATEGORY_LABELS),
+    tag: listOf(p, 'tag', true).map((t) => t.toLowerCase()),
+    stack: listOf(p, 'stack', false),
+    has: listOf(p, 'has', true).filter((h) => h in HAS),
+    maker: listOf(p, 'maker', false),
+    launched: launched in LAUNCHED ? launched : null,
+    sort: sort in SORTS && (sort !== 'relevance' || q) ? sort : q ? 'relevance' : 'top',
+    page: Math.min(500, Math.max(1, Number(p.get('page')) || 1)),
+  }
+}
+
+/** The query as URL parameters; defaults left out so links stay short. */
+export function queryString(q: Query): string {
+  const p = new URLSearchParams()
+  if (q.q) p.set('q', q.q)
+  for (const k of ['category', 'tag', 'has', 'stack', 'maker'] as const) for (const v of q[k]) p.append(k, v)
+  if (q.launched) p.set('launched', q.launched)
+  if (q.sort !== (q.q ? 'relevance' : 'top')) p.set('sort', q.sort)
+  if (q.page > 1) p.set('page', String(q.page))
+  return p.toString()
+}
+
+/** The same query with one facet value switched on or off (back to page 1). */
+export function toggle(q: Query, facet: FacetName, value: string): Query {
+  const next: Query = { ...q, page: 1 }
+  if (facet === 'launched') next.launched = q.launched === value ? null : value
+  else next[facet] = q[facet].includes(value) ? q[facet].filter((v) => v !== value) : [...q[facet], value]
+  return next
+}
+
+export const isEmpty = (q: Query) => !q.q && !q.launched && !q.category.length && !q.tag.length && !q.stack.length && !q.has.length && !q.maker.length
+
+const words = (s: string) => s.toLowerCase().split(/[^a-z0-9+#.]+/).filter((w) => w.length >= 2)
+
+export function search(all: Product[], query: Query, o: { limit?: number; now?: number } = {}): Result {
+  const now = o.now ?? Date.now()
+  const limit = o.limit ?? 30
+  const categories = new Map(all.map((p) => [p.id, categorize(p)]))
+  const stackOf = (p: Product) => [...new Set((p.extras.stack?.items ?? []).map((i) => i.name))]
+
+  // Words: every one must appear somewhere; where it appears decides the score.
+  // A term matches at the start of a word: "crypt" finds crypto, "ai" does not find email.
+  const terms = words(query.q).map((t) => ({ t, re: new RegExp(`(?:^|[^a-z0-9])${escRe(t)}`) }))
+  const scores = new Map<string, number>()
+  const textMatch = (p: Product) => {
+    if (!terms.length) return true
+    const name = p.name.toLowerCase()
+    const fields = [
+      [name, 8],
+      [p.tags.join(' ').toLowerCase(), 5],
+      [(categories.get(p.id) ?? []).map((c) => CATEGORY_LABELS[c]).join(' ').toLowerCase(), 4],
+      [p.domain.toLowerCase(), 4],
+      [p.tagline.toLowerCase(), 3],
+      [`${p.makerName} ${stackOf(p).join(' ')}`.toLowerCase(), 2],
+      [p.description.toLowerCase(), 1],
+    ] as const
+    let score = 0
+    for (const { re } of terms) {
+      const hit = fields.reduce((best, [text, w]) => (re.test(text) ? Math.max(best, w) : best), 0)
+      if (!hit) return false
+      score += hit
+    }
+    if (name === query.q.toLowerCase()) score += 20
+    else if (name.startsWith(terms[0]!.t)) score += 6
+    scores.set(p.id, score)
+    return true
+  }
+
+  const tests: Record<FacetName, (p: Product) => boolean> = {
+    category: (p) => !query.category.length || query.category.some((c) => categories.get(p.id)!.includes(c)),
+    tag: (p) => !query.tag.length || query.tag.some((t) => p.tags.includes(t)),
+    stack: (p) => !query.stack.length || stackOf(p).some((s) => query.stack.includes(s)),
+    has: (p) => query.has.every((h) => HAS[h]!.test(p, now)),
+    maker: (p) => !query.maker.length || query.maker.includes(p.makerName),
+    launched: (p) => !query.launched || Boolean(p.launchedAt && p.launchedAt >= now - LAUNCHED[query.launched]!.ms),
+  }
+  const base = all.filter(textMatch)
+  const names = Object.keys(tests) as FacetName[]
+  const passes = (p: Product, except?: FacetName) => names.every((n) => n === except || tests[n](p))
+
+  // Each facet counts over everything the other facets allow.
+  const tally = (except: FacetName, valuesOf: (p: Product) => string[]) => {
+    const n = new Map<string, number>()
+    for (const p of base) if (passes(p, except)) for (const v of valuesOf(p)) n.set(v, (n.get(v) ?? 0) + 1)
+    return n
+  }
+  const ranked = (n: Map<string, number>, label: (v: string) => string, top = 100, selected: string[] = []) =>
+    [...n]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .filter(([v], i) => i < top || selected.includes(v))
+      .map(([value, count]) => ({ value, label: label(value), count }))
+  const withSelected = (values: FacetValue[], selected: string[], label: (v: string) => string) => [...values, ...selected.filter((s) => !values.some((v) => v.value === s)).map((s) => ({ value: s, label: label(s), count: 0 }))]
+
+  const hasCounts = new Map<string, number>()
+  for (const p of base) if (passes(p, 'has')) for (const [k, h] of Object.entries(HAS)) if (query.has.filter((x) => x !== k).every((x) => HAS[x]!.test(p, now)) && h.test(p, now)) hasCounts.set(k, (hasCounts.get(k) ?? 0) + 1)
+  const launchedCounts = new Map<string, number>()
+  for (const p of base) if (passes(p, 'launched')) for (const [k, l] of Object.entries(LAUNCHED)) if (p.launchedAt && p.launchedAt >= now - l.ms) launchedCounts.set(k, (launchedCounts.get(k) ?? 0) + 1)
+
+  const facets: Facets = {
+    category: withSelected(ranked(tally('category', (p) => categories.get(p.id)!), (v) => CATEGORY_LABELS[v] ?? v), query.category, (v) => CATEGORY_LABELS[v] ?? v),
+    tag: withSelected(ranked(tally('tag', (p) => p.tags), (v) => v, 30, query.tag), query.tag, (v) => v),
+    stack: withSelected(ranked(tally('stack', stackOf), (v) => v, 20, query.stack), query.stack, (v) => v),
+    maker: withSelected(ranked(tally('maker', (p) => (p.makerName ? [p.makerName] : [])), (v) => v, 20, query.maker), query.maker, (v) => v),
+    has: Object.keys(HAS).filter((k) => hasCounts.get(k) || query.has.includes(k)).map((k) => ({ value: k, label: HAS[k]!.label, count: hasCounts.get(k) ?? 0 })),
+    launched: Object.keys(LAUNCHED).filter((k) => launchedCounts.get(k) || query.launched === k).map((k) => ({ value: k, label: LAUNCHED[k]!.label, count: launchedCounts.get(k) ?? 0 })),
+  }
+
+  const matched = base.filter((p) => passes(p))
+  const by: Record<Sort, (a: Product, b: Product) => number> = {
+    relevance: (a, b) => (scores.get(b.id) ?? 0) - (scores.get(a.id) ?? 0) || b.votes - a.votes,
+    top: (a, b) => b.votes - a.votes || (b.launchedAt ?? 0) - (a.launchedAt ?? 0),
+    new: (a, b) => (b.launchedAt ?? 0) - (a.launchedAt ?? 0),
+    name: (a, b) => a.name.localeCompare(b.name, 'en', { sensitivity: 'base' }),
+  }
+  matched.sort(by[query.sort])
+
+  const chips: Chip[] = [
+    ...(query.q ? [{ facet: 'q' as const, value: query.q, label: `“${query.q}”` }] : []),
+    ...query.category.map((v) => ({ facet: 'category' as const, value: v, label: CATEGORY_LABELS[v] ?? v })),
+    ...query.tag.map((v) => ({ facet: 'tag' as const, value: v, label: `#${v}` })),
+    ...(query.launched ? [{ facet: 'launched' as const, value: query.launched, label: LAUNCHED[query.launched]!.label }] : []),
+    ...query.has.map((v) => ({ facet: 'has' as const, value: v, label: HAS[v]!.label })),
+    ...query.stack.map((v) => ({ facet: 'stack' as const, value: v, label: `Built with ${v}` })),
+    ...query.maker.map((v) => ({ facet: 'maker' as const, value: v, label: `By ${v}` })),
+  ]
+  const start = (query.page - 1) * limit
+  return { query, total: matched.length, products: matched.slice(start, start + limit), facets, chips, categories, limit }
+}

package/src/cli.ts

@@ -7,9 +7,23 @@
  *   builtindie show <slug>
  *   builtindie vote <slug>
  *   builtindie preview <url>           what we would read from a site, nothing saved
- *   builtindie search <words>
- *   builtindie claim <slug>            prove you own the domain (DNS TXT), BUILTINDIE_KEY
+ *   builtindie tags [tag]              every tag, or the launches with one
+ *   builtindie search [words] [--category k] [--tag t] [--has h] [--sort top|new|name]
+ *   builtindie categories              every category and tag, with counts
+ *   builtindie claim <slug>            prove you own the domain (the badge or DNS TXT), BUILTINDIE_KEY
  *   builtindie me                      your launches, BUILTINDIE_KEY
+ *   builtindie invite                  your invite link and free Featured credits, BUILTINDIE_KEY
+ *   builtindie credit <slug>           spend a credit: feature a listing you own, BUILTINDIE_KEY
+ *   builtindie redeem <code>           a credit code: Featured days to your balance, BUILTINDIE_KEY
+ *   builtindie invite-code [note]      one of your 3 single-use invite codes, BUILTINDIE_KEY
+ *   builtindie feature-days <slug> <n> spend Featured days on a listing you own, BUILTINDIE_KEY
+ *   builtindie feature <slug>          pay to feature it: a CoinPay checkout link (any coin or PayPal), BUILTINDIE_KEY
+ *   builtindie karma                   your karma, history, next free Featured week, BUILTINDIE_KEY
+ *   builtindie leaderboard [karma|invites] [--period week|month|all]
+ *   builtindie comment <slug> "text"   comment on a launch (--reply <id>), BUILTINDIE_KEY
+ *   builtindie comments <slug>         read the comments
+ *   builtindie review <slug> <1-5> "text"   review a launch, BUILTINDIE_KEY
+ *   builtindie reviews <slug>          read the reviews
  *   builtindie edit <slug> --tagline … (BUILTINDIE_KEY)
  *   builtindie refetch <slug>          (BUILTINDIE_KEY)
  *   builtindie mcp                     MCP server on stdio
@@ -27,10 +41,28 @@ export const HELP = `builtindie ${VERSION}: launch your indie product with one U
   builtindie show <slug>
   builtindie vote <slug>
   builtindie preview <url>            what we read from a site; nothing is saved
-  builtindie search <words>
-  builtindie claim <slug> [--md]      the DNS TXT record that proves it is yours, then checks it;
-                                      --md prints the steps as Markdown to paste to an AI with DNS access
+  builtindie tags [tag]               every tag with its count, or the launches tagged <tag>
+  builtindie search [words]           search; narrow with --category developer-tools --tag ai
+        [--has verified,video] [--stack Bun] [--maker "Name"] [--launched today|week|month|year]
+        [--sort relevance|top|new|name] [--page N] [--facets]
+  builtindie categories               every category and tag, with how many launches each
+  builtindie claim <slug> [--md]      your badge for the homepage (or the DNS TXT record) that proves
+                                      it is yours, then checks both; --md prints the steps as Markdown
+                                      to paste to an AI with DNS or site access
   builtindie me                       your launches
+  builtindie invite                   your invite link; each maker it brings in who launches = a free Featured week
+  builtindie credit <slug>            spend a credit to feature a listing you own
+  builtindie redeem <code>            redeem a credit code: Featured days to your balance
+  builtindie invite-code [note]       make one of your 3 single-use invite codes (both get Featured days)
+  builtindie feature-days <slug> <n>  spend n Featured days on a listing you own
+  builtindie feature <slug> [--email you@x]  pay to feature it: prints a CoinPay checkout link (any coin or PayPal)
+  builtindie karma                    your karma, history and how far to the next free Featured week
+  builtindie leaderboard [karma|invites] [--period week|month|all]
+  builtindie comment <slug> "text"    comment on a launch (+2 karma); --reply <comment id> to answer one
+  builtindie comments <slug>          read a launch's comments
+  builtindie uncomment <id>           delete your comment (its karma goes back)
+  builtindie review <slug> <1-5> "text"   stars and words (+5 karma for 30+ characters)
+  builtindie reviews <slug>           read a launch's reviews
   builtindie edit <slug> [--name --tagline --description --tags a,b --video URL]
   builtindie refetch <slug>           read the homepage again
   builtindie publish <slug>           put a draft live
@@ -54,7 +86,7 @@ export function parseArgs(argv: string[]): { words: string[]; flags: Record<stri
     if (a.startsWith('--')) {
       const [k, v] = a.slice(2).split(/=(.*)/s) as [string, string | undefined]
       if (v !== undefined) flags[k] = v
-      else if (argv[i + 1] !== undefined && !argv[i + 1]!.startsWith('--') && !['json', 'draft', 'md'].includes(k)) flags[k] = argv[++i]!
+      else if (argv[i + 1] !== undefined && !argv[i + 1]!.startsWith('--') && !['json', 'draft', 'md', 'facets'].includes(k)) flags[k] = argv[++i]!
       else flags[k] = true
     } else words.push(a)
   }
@@ -135,8 +167,26 @@ export async function main(argv = process.argv.slice(2), out: Out = console, cli
         return 0
       }
       case 'search': {
-        const r = await client.search(rest.join(' '))
-        show(r, r.products.map((p) => line(p)).join('\n') || 'Nothing matches.')
+        const many = (k: string) => (typeof flags[k] === 'string' ? String(flags[k]).split(',').map((v) => v.trim()).filter(Boolean) : undefined)
+        const r = await client.search(rest.join(' '), { category: many('category'), tag: many('tag'), has: many('has'), stack: many('stack'), maker: typeof flags.maker === 'string' ? [flags.maker] : undefined, launched: str('launched'), sort: str('sort'), page: Number(str('page') ?? 1) || 1, limit: Number(str('limit') ?? 30) || 30 })
+        const facets = flags.facets && r.facets ? `\n\n${Object.entries(r.facets).filter(([, v]) => v.length).map(([k, v]) => `${k}: ${v.map((f) => `${f.value} (${f.count})`).join(', ')}`).join('\n')}` : ''
+        show(r, `${r.products.map((p) => line(p)).join('\n') || 'Nothing matches.'}\n\n${r.total} match${r.total === 1 ? '' : 'es'}${r.pages > 1 ? `, page ${r.page} of ${r.pages}` : ''} · ${r.web}${facets}`)
+        return 0
+      }
+      case 'categories': {
+        const r = await client.categories()
+        show(r, `${r.categories.map((c) => `${String(c.count).padStart(4)}  ${c.label} (${c.key})`).join('\n')}\n\nTags: ${r.tags.map((t) => `${t.tag} (${t.count})`).join(', ')}`)
+        return 0
+      }
+      case 'tags':
+      case 'tag': {
+        if (rest.length) {
+          const r = await client.tagged(rest.join(' '), Number(str('limit') ?? 30))
+          show(r, r.products.map((p, i) => line(p, i + 1)).join('\n') || `Nothing tagged ${r.tag} yet.`)
+        } else {
+          const r = await client.tags()
+          show(r, r.tags.map((t) => `${String(t.count).padStart(4)}  ${t.tag}`).join('\n') || 'No tags yet.')
+        }
         return 0
       }
       case 'show': {
@@ -179,8 +229,8 @@ export async function main(argv = process.argv.slice(2), out: Out = console, cli
           return 0
         }
         const r = await client.claim(slug)
-        if (r.claimed) return show(r, `${slug} is yours ✓. Edit it: builtindie edit ${slug} --tagline "…"`), 0
-        show(r, `Add this DNS record, wait a minute, then run builtindie claim ${slug} again:\n\n  type   TXT\n  name   ${r.record.name}\n  value  ${r.record.value}\n\n(not found yet at ${r.looked.join(', ')})`)
+        if (r.claimed) return show(r, `${slug} is yours ✓${r.method === 'badge' ? ' (we found your badge)' : r.method === 'dns' ? ' (we found your DNS record)' : ''}. Edit it: builtindie edit ${slug} --tagline "…"`), 0
+        show(r, `Prove it either way, then run builtindie claim ${slug} again:\n\n1. Easiest: put this badge on your homepage and deploy (its id is yours; it also earns the followed link and the ✓):\n\n  ${r.badge}\n\n2. Or add this DNS record (wait a minute for it to show):\n\n  type   TXT\n  name   ${r.record.name}\n  value  ${r.record.value}\n\n(not found yet at ${r.looked.join(', ')})`)
         return 1
       }
       case 'me': {
@@ -188,6 +238,77 @@ export async function main(argv = process.argv.slice(2), out: Out = console, cli
         show(r, `${r.email}\n${r.products.map((p) => `${line(p)}  ${p.owner ? 'claimed ✓' : p.status === 'draft' ? 'draft' : 'not claimed'}`).join('\n') || 'No launches yet.'}`)
         return 0
       }
+      case 'invite':
+      case 'invites': {
+        const r = await client.invites()
+        show(r, `Your invite link: ${r.link}\n${r.invited} joined · ${r.launched} launched · ${r.credits} free Featured week${r.credits === 1 ? '' : 's'} to use (${r.feature_days} days each)${r.credits ? '\nUse one: builtindie credit <slug>' : ''}`)
+        return 0
+      }
+      case 'credit': {
+        const r = await client.credit(rest[0] ?? '')
+        show(r, `${rest[0]} is Featured until ${r.featured_until.slice(0, 10)} ★  (${r.credits} credit${r.credits === 1 ? '' : 's'} left)`)
+        return 0
+      }
+      case 'redeem': {
+        const r = await client.redeem(rest[0] ?? '')
+        show(r, `${r.message}\nFeatured days: ${r.featured_days}${r.featured_days ? '  (use them: builtindie feature-days <slug> <n>)' : ''}`)
+        return 0
+      }
+      case 'invite-code': {
+        const r = await client.inviteCode(rest.join(' '))
+        show(r, `Your invite (works once, for someone new; you both get ${r.bonus_days} Featured days):\n${r.link}\n${r.left} left`)
+        return 0
+      }
+      case 'feature-days': {
+        const r = await client.featureDays(rest[0] ?? '', Number(rest[1] ?? 0))
+        show(r, `${rest[0]} is Featured until ${r.featured_until.slice(0, 10)} ★  (${r.featured_days} day${r.featured_days === 1 ? '' : 's'} left)`)
+        return 0
+      }
+      case 'feature': {
+        const r = await client.feature(rest[0] ?? '', str('email'))
+        show(r, `Pay $${r.usd} for ${r.days} days Featured (${r.methods.join(', ')}):\n${r.checkout_url}`)
+        return 0
+      }
+      case 'karma': {
+        const r = await client.karma()
+        show(r, `${r.total} karma (${r.week >= 0 ? '+' : ''}${r.week} this week) · ${r.next_credit_in} to your next free Featured week · ${r.credits.earned} earned from karma\n\n${r.events.map((e) => `${(e.points > 0 ? '+' : '') + e.points}`.padStart(4) + `  ${e.label}  ${e.at.slice(0, 10)}`).join('\n') || 'No karma yet. How to earn:\n' + r.how_to_earn.map((h) => `  +${h.points}  ${h.action}: ${h.rule}`).join('\n')}`)
+        return 0
+      }
+      case 'leaderboard':
+      case 'board': {
+        const r = await client.leaderboard(rest[0] ?? 'karma', str('period') ?? 'week', Number(str('limit') ?? 25))
+        show(r, `${r.board === 'invites' ? 'Top inviters' : 'Top karma'} (${r.period})\n${r.rows.map((x) => `${String(x.rank ?? '').padStart(3)}. ${String(x.value).padStart(5)}  ${x.name} ${x.badges.map((b) => b.emoji).join('')}`).join('\n') || 'Nobody yet.'}\n${r.web}`)
+        return 0
+      }
+      case 'comment': {
+        const [slug, ...text] = rest
+        if (!slug || !text.length) throw new Error('builtindie comment <slug> "text" [--reply <comment id>]')
+        const r = await client.comment(slug, text.join(' '), str('reply'))
+        show(r, `Posted: ${r.comment.url}  (you have ${r.karma} karma)`)
+        return 0
+      }
+      case 'comments': {
+        const r = await client.comments(rest[0] ?? '')
+        show(r, r.comments.map((x) => `${x.parent ? '    ↳ ' : ''}${x.deleted ? '[deleted]' : `${x.author} (${x.karma} karma)${x.maker ? ' [maker]' : ''} ${x.at.slice(0, 10)}  #${x.id}\n${x.parent ? '      ' : '  '}${x.body}`}`).join('\n') || 'No comments yet.')
+        return 0
+      }
+      case 'uncomment': {
+        const r = await client.deleteComment(rest[0] ?? '')
+        show(r, 'Deleted.')
+        return 0
+      }
+      case 'review': {
+        const [slug, stars, ...text] = rest
+        if (!slug || !stars) throw new Error('builtindie review <slug> <1-5> "text"')
+        const r = await client.review(slug, Number(stars), text.join(' '))
+        show(r, `${'★'.repeat(r.review.rating)} saved. ${slug} is rated ${r.product.rating} from ${r.product.count}. You have ${r.karma} karma.`)
+        return 0
+      }
+      case 'reviews': {
+        const r = await client.reviews(rest[0] ?? '')
+        show(r, `${r.rating === null ? 'No reviews yet.' : `★ ${r.rating} from ${r.count}`}\n${r.reviews.map((x) => `${'★'.repeat(x.rating)}  ${x.author} (${x.karma} karma) ${x.at.slice(0, 10)}\n  ${x.body}`).join('\n')}`)
+        return 0
+      }
       case 'verify': {
         const r = await client.verify(rest[0] ?? '')
         show(r, r.verified ? 'Verified ✓: we found the badge.' : 'Not found yet: add the badge HTML to your homepage and deploy.')

package/src/client.ts

@@ -3,6 +3,10 @@
  * BUILTINDIE_URL points it at another instance; BUILTINDIE_KEY (bi_…) is your
  * account's API key (built.indie/me), for claiming and editing your products.
  */
+export type SearchFilters = Partial<{ category: string[]; tag: string[]; has: string[]; stack: string[]; maker: string[]; launched: string; sort: string; page: number; limit: number }>
+export type FacetValue = { value: string; label: string; count: number }
+export type SearchResult = { total: number; page: number; pages: number; products: (ApiProduct & { categories: string[] })[]; facets?: Record<string, FacetValue[]>; web: string }
+
 export type ApiProduct = {
   slug: string
   name: string
@@ -12,6 +16,8 @@ export type ApiProduct = {
   domain: string
   status: string
   votes: number
+  reviews?: number
+  rating?: number | null
   tags: string[]
   logo: string | null
   card_image: string | null
@@ -32,6 +38,13 @@ export type ApiProduct = {
   award?: { day: string; rank: number } | null
 }
 
+export type Invites = { link: string; code: string; invited: number; launched: number; credits: number; karma_credits?: number; used: number; feature_days: number; invite_codes?: { quota: { total: number; used: number; left: number }; bonus_days: number; invites: { id: string; note: string; created_at: string; expires_at: string | null; used: boolean; used_at: string | null }[] } }
+
+export type KarmaInfo = { total: number; week: number; per_credit: number; next_credit_in: number; credits: { earned: number; used: number }; events: { action: string; label: string; ref: string; points: number; at: string }[]; how_to_earn: { action: string; points: number; rule: string }[]; leaderboard: string }
+export type BoardRows = { board: string; period: string; total: number; rows: { rank: number | null; id: string; name: string; value: number; badges: { emoji: string; label: string }[]; url: string }[]; web: string }
+export type ApiComment = { id: string; parent: string | null; body: string | null; deleted: boolean; author: string | null; karma: number; maker: boolean; at: string; url: string; mine?: boolean }
+export type ApiReview = { rating: number; body: string; author: string; karma: number; at: string }
+
 export type Launched = { product: ApiProduct; claim_url?: string; existing?: boolean }
 export type ClaimRecord = { type: string; name: string; value: string }
 
@@ -71,8 +84,27 @@ export class BuiltIndieClient {
     return this.call('GET', `/api/v1/products?window=${encodeURIComponent(window)}&limit=${limit}`)
   }
 
-  search(q: string): Promise<{ products: ApiProduct[] }> {
-    return this.call('GET', `/api/v1/products?q=${encodeURIComponent(q)}`)
+  tags(): Promise<{ tags: { tag: string; count: number }[] }> {
+    return this.call('GET', '/api/v1/tags')
+  }
+
+  tagged(tag: string, limit = 30): Promise<{ tag: string; products: ApiProduct[] }> {
+    return this.call('GET', `/api/v1/products?tag=${encodeURIComponent(tag)}&limit=${limit}`)
+  }
+
+  /** Search with filters; the answer carries the facets (counts per category, tag, stack…) to narrow further. */
+  search(q: string, filters: SearchFilters = {}): Promise<SearchResult> {
+    const p = new URLSearchParams()
+    if (q) p.set('q', q)
+    for (const k of ['category', 'tag', 'has', 'stack', 'maker'] as const) for (const v of filters[k] ?? []) p.append(k, v)
+    for (const k of ['launched', 'sort'] as const) if (filters[k]) p.set(k, filters[k]!)
+    if (filters.page) p.set('page', String(filters.page))
+    if (filters.limit) p.set('limit', String(filters.limit))
+    return this.call('GET', `/api/v1/search?${p}`)
+  }
+
+  categories(): Promise<{ categories: { key: string; label: string; count: number; page: string }[]; tags: { tag: string; count: number; page: string }[] }> {
+    return this.call('GET', '/api/v1/categories')
   }
 
   product(slug: string): Promise<ApiProduct> {
@@ -89,18 +121,48 @@ export class BuiltIndieClient {
     return k
   }
 
-  claimRecord(slug: string): Promise<{ owner: boolean; record: ClaimRecord; markdown: string }> {
+  claimRecord(slug: string): Promise<{ owner: boolean; record: ClaimRecord; badge: string; markdown: string }> {
     return this.call('GET', `/api/v1/products/${encodeURIComponent(slug)}/claim`, undefined, this.needKey())
   }
 
-  claim(slug: string): Promise<{ claimed: boolean; looked: string[]; record: ClaimRecord; markdown?: string }> {
+  claim(slug: string): Promise<{ claimed: boolean; method?: 'dns' | 'badge'; looked: string[]; record: ClaimRecord; badge: string; markdown?: string }> {
     return this.call('POST', `/api/v1/products/${encodeURIComponent(slug)}/claim`, {}, this.needKey())
   }
 
-  me(): Promise<{ email: string; products: (ApiProduct & { owner: boolean })[] }> {
+  me(): Promise<{ email: string; products: (ApiProduct & { owner: boolean })[]; invite: Invites }> {
     return this.call('GET', '/api/v1/me', undefined, this.needKey())
   }
 
+  /** Your invite link and credits: each new member it brings in who launches earns a free Featured week. */
+  invites(): Promise<Invites> {
+    return this.call('GET', '/api/v1/invites', undefined, this.needKey())
+  }
+
+  /** Spend one invite credit to feature a listing you own. */
+  credit(slug: string): Promise<{ featured_until: string; credits: number }> {
+    return this.call('POST', `/api/v1/products/${encodeURIComponent(slug)}/credit`, {}, this.needKey())
+  }
+
+  /** Redeem a credit code: Featured days added to your balance. */
+  redeem(code: string): Promise<{ ok: boolean; message: string; featured_days: number }> {
+    return this.call('POST', '/api/v1/redeem', { code }, this.needKey())
+  }
+
+  /** Make one of your scarce single-use invite codes; the link is shown once. */
+  inviteCode(note = ''): Promise<{ link: string; code: string; expires_at: string | null; left: number; bonus_days: number }> {
+    return this.call('POST', '/api/v1/invites', { note }, this.needKey())
+  }
+
+  /** Spend Featured days from your balance on a listing you own. */
+  featureDays(slug: string, days: number): Promise<{ featured_until: string; featured_days: number }> {
+    return this.call('POST', `/api/v1/products/${encodeURIComponent(slug)}/feature-days`, { days }, this.needKey())
+  }
+
+  /** Pay to feature a listing you own: opens a CoinPay checkout session (any coin or PayPal); send the buyer to checkout_url. */
+  feature(slug: string, email?: string): Promise<{ checkout_url: string; checkout_session_id: string; methods: string[]; payment: string; usd: number; days: number }> {
+    return this.call('POST', `/api/v1/products/${encodeURIComponent(slug)}/feature`, email ? { email } : {}, this.needKey())
+  }
+
   edit(slug: string, patch: Record<string, unknown>, key?: string): Promise<ApiProduct> {
     return this.call('PATCH', `/api/v1/products/${encodeURIComponent(slug)}`, patch, this.needKey(key))
   }
@@ -109,6 +171,35 @@ export class BuiltIndieClient {
     return this.call('POST', `/api/v1/products/${encodeURIComponent(slug)}/${action}`, {}, this.needKey(key))
   }
 
+  /** Your karma: total, this week, history, and how far to the next free Featured week. */
+  karma(): Promise<KarmaInfo> {
+    return this.call('GET', '/api/v1/karma', undefined, this.needKey())
+  }
+
+  leaderboard(board = 'karma', period = 'week', limit = 25): Promise<BoardRows> {
+    return this.call('GET', `/api/v1/leaderboard?board=${encodeURIComponent(board)}&period=${encodeURIComponent(period)}&limit=${limit}`)
+  }
+
+  comments(slug: string): Promise<{ slug: string; comments: ApiComment[] }> {
+    return this.call('GET', `/api/v1/products/${encodeURIComponent(slug)}/comments`)
+  }
+
+  comment(slug: string, body: string, parent?: string): Promise<{ comment: ApiComment; karma: number }> {
+    return this.call('POST', `/api/v1/products/${encodeURIComponent(slug)}/comments`, { body, ...(parent ? { parent } : {}) }, this.needKey())
+  }
+
+  deleteComment(id: string): Promise<{ deleted: boolean }> {
+    return this.call('DELETE', `/api/v1/comments/${encodeURIComponent(id)}`, undefined, this.needKey())
+  }
+
+  reviews(slug: string): Promise<{ slug: string; rating: number | null; count: number; reviews: ApiReview[] }> {
+    return this.call('GET', `/api/v1/products/${encodeURIComponent(slug)}/reviews`)
+  }
+
+  review(slug: string, rating: number, body: string): Promise<{ review: { rating: number; body: string }; product: { rating: number | null; count: number }; karma: number }> {
+    return this.call('POST', `/api/v1/products/${encodeURIComponent(slug)}/reviews`, { rating, body }, this.needKey())
+  }
+
   verify(slug: string): Promise<{ verified: boolean }> {
     return this.call('POST', `/api/v1/products/${encodeURIComponent(slug)}/verify`, {})
   }