pet-project: build a typescript/bun cli tool/tui for sedekah.je API (idea by farhanhelmy)

[khrnchn]

Summary

A TypeScript/Bun CLI tool (sedekah) for developers to interact with the sedekah.je public API — search institutions, view details, render QR codes in the terminal, and onboard as a partner.

Phased Approach

Phase 1 — Minimal CLI

sedekah search "masjid" --state selangor --category masjid
sedekah random
sedekah info <slug>
sedekah qr <slug>        # render QR code in terminal

Phase 2 — TUI (sedekah browse)

Two-pane OpenTUI interface:

• Left panel: Scrollable institution list with search + filter pills
• Right panel: Institution detail + inline QR code
• Live fuzzy search, keyboard nav (j/k), filter popup (state/category/payment)
• o to open in browser, r for random, Tab to switch panes

TUI sketch: https://excalidraw.com/#json=4bfKTbIqWmy8m28aCbzoP,oZeSZNTD0FNpF3ZVwDZq2Q

Phase 3 — Partner Onboarding TUI (relates to #554)

Interactive wizard for partner registration and management:

sedekah partner register    # step-by-step onboarding wizard
sedekah partner status      # check registration/approval status
sedekah partner stats       # view API usage, rate limits, request counts
sedekah partner key rotate  # rotate API key

sedekah partner register wizard flow:

┌─────────────────────────────────────────────┐
│  sedekah — Partner Registration             │
├─────────────────────────────────────────────┤
│                                             │
│  Step 1 of 4: About You                    │
│                                             │
│  App Name:     SolatKini█                   │
│  Email:        dev@solatkini.my             │
│  Website:      https://solatkini.my         │
│                                             │
│  ────────────────────────────────────────   │
│  Step 2 of 4: Use Case                     │
│                                             │
│  ○ Mosque finder / prayer app              │
│  ● Donation aggregator                     │
│  ○ Community platform                      │
│  ○ Other                                   │
│                                             │
│  Describe your integration:                │
│  ┌─────────────────────────────────────┐   │
│  │ We want to add QR donations to our  │   │
│  │ existing mosque directory...         │   │
│  └─────────────────────────────────────┘   │
│                                             │
│         [Back]  [Next]  [Cancel]            │
└─────────────────────────────────────────────┘

On approval, the CLI can store the API key locally (~/.config/sedekah/credentials.json) and unlock partner-only commands:

sedekah institutions --limit 200     # higher rate limits
sedekah bulk export                  # cursor-based full sync
sedekah submit <institution>         # submit via partner API

API Surface (REST)

• GET /api/institutions — paginated list with search, category, state filters
• GET /api/random — random institution
• Partner API endpoints from feat: Partner API for Mosque Apps (Data + QR Embed) #554 (Phase 3)

Tech Stack

Phase 1 — CLI

• Runtime: Bun (compile to single binary via bun build --compile)
• Arg parsing: commander or citty
• QR rendering: qrcode-terminal
• HTTP: native fetch
• Output: --json flag for machine-readable output

Phase 2 & 3 — TUI

• Framework: OpenTUI with @opentui/react
• Components: opentui-ui component library
• Scaffold: bun create tui

Distribution

• GitHub Releases — single compiled binary per platform (linux/mac/windows)
• npm — bunx sedekah / npx sedekah
• Homebrew tap — brew install khrnchn/tap/sedekah (stretch goal)

References

• OpenTUI — Zig core + TS bindings TUI framework
• awesome-opentui — community components and examples
• feat: Partner API for Mosque Apps (Data + QR Embed) #554 — Partner API spec (Phase 3 depends on this)

Notes

• Hits the REST API (simpler than MCP JSON-RPC for a CLI client)
• No DB needed — stateless thin client over existing sedekah.je API
• The killer feature: scan and donate without leaving the terminal
• Partner onboarding via TUI gives devs a native-feeling registration experience

[khrnchn]

drew by claude via excalidraw mcp btw:

[faizkhairi]

Hi @khrnchn! I'd like to build Phase 1 of the CLI tool as described in this issue about search, random, and QR commands using the public API. Will use Bun + Commander as the runtime. Will submit a PR with the initial implementation shortly.

[faizkhairi]

Phase 1 of the CLI tool is ready: https://github.com/faizkhairi/sedekah-cli

What's implemented

• sedekah search [query] -- search institutions with --state, --category, --limit, --page, --json flags
• sedekah random -- display a random institution with --json flag
• sedekah qr <name> -- render an institution's QR code in the terminal

Tech stack

TypeScript, Commander, qrcode-terminal, Node.js native fetch (no Bun-specific APIs for broad compatibility)

API usage

• GET /api/institutions with search/state/category/limit/page params
• GET /api/random for random institution
• Uses qrContent field (100% populated) for terminal QR rendering

What's not yet implemented (Phase 2+)

• sedekah info <slug> -- no /api/institutions/:slug endpoint exists yet
• sedekah browse -- TUI mode (Phase 2 from the issue spec)
• sedekah partner -- Partner API commands (depends on feat: Partner API for Mosque Apps (Data + QR Embed) #554)

Happy to submit this as a PR if you'd prefer it as a directory inside the sedekah-je repo rather than a standalone package. Let me know your preference!

[khrnchn]

Hi @khrnchn! I'd like to build Phase 1 of the CLI tool as described in this issue -- search, random, and QR commands using the public API. Will use Bun + Commander as the runtime. Will submit a PR with the initial implementation shortly.

damn, appreciate it faiz, but actually 2 people built the tui including me, this is my version - https://github.com/khrnchn/sedekahje-cli, you can checkout its README. sorry i didnt update the issue hshs

[faizkhairi]

Hi @khrnchn! I'd like to build Phase 1 of the CLI tool as described in this issue -- search, random, and QR commands using the public API. Will use Bun + Commander as the runtime. Will submit a PR with the initial implementation shortly.

damn, appreciate it faiz, but actually 2 people built the tui including me, this is my version - https://github.com/khrnchn/sedekahje-cli, you can checkout its README. sorry i didnt update the issue hshs

hshshhs xDDD, takde hal okay jeee