SMSHub

A multi-platform, real-time SMS messaging platform with unified inbox, multi-provider support (Twilio + Telnyx), and an API-first architecture.

🚀 Coming Soon: phonenumbers.bot — Real SIM phone numbers with a developer-first API

Install the CLI (rent numbers, read texts and codes from a terminal or an agent):

curl -fsSL https://smshub.dev/cli/install.sh | sh

https://smshub.dev/install.sh stays the desktop app installer.

• Unified Inbox — Threaded conversations across all devices
• Real-time Messaging — Sub-second updates via Supabase Realtime
• Multi-Provider — Twilio + Telnyx with unified API (sendSMS())
• Compose Flow — New message modal with sender number picker
• Unread Tracking — Badge counts, auto-mark read on open
• Search — Filter conversations by name or phone number
• Contact Management — Auto-create on inbound, inline name editing
• Delivery Receipts — Live status updates (queued → sent → delivered → failed)
• Keyboard Shortcuts — Ctrl+N (compose), Ctrl+K (search), arrows, Escape
• Push Notifications — Native on mobile (Expo), OS notifications on desktop (Electron)
• PWA — Installable, offline support, background sync
• Dark Mode — Default, developer-focused UI

• Bun 1.4 (package manager and runtime for the web app)
• pnpm (for mobile/ and electron/ only)
• A Supabase project
• Twilio and/or Telnyx account(s)

# Install dependencies
bun install

# Copy env file and fill in your values
cp .env.example .env

# Run database migrations against your Supabase project
# (paste supabase/migrations/*.sql into the Supabase SQL editor)

# Start dev server
bun dev

cd mobile
pnpm install
npx expo start

# Build for iOS/Android via Expo EAS
eas build --profile production --platform all

cd electron
pnpm install
pnpm dev

# Package distributable
pnpm package

src/                          # Web app (Next.js)
├── app/
│   ├── api/
│   │   ├── contacts/         # GET, PATCH /api/contacts/[id]
│   │   ├── conversations/    # GET, POST /api/conversations/[id]/read
│   │   ├── messages/         # GET, POST /api/messages/send
│   │   ├── providers/        # DELETE /api/providers/[id]
│   │   ├── phone-numbers/    # DELETE /api/phone-numbers/[id]
│   │   └── webhooks/         # Twilio + Telnyx inbound & status callbacks
│   ├── login/                # Login page
│   ├── register/             # Register page
│   ├── settings/             # Provider & phone number management
│   ├── phonenumbers/         # phonenumbers.bot coming soon page
│   └── offline/              # PWA offline fallback
├── components/
│   ├── inbox-client.tsx      # Main inbox (sidebar + chat + realtime)
│   ├── new-message-modal.tsx # Compose new conversation
│   ├── contact-name-editor.tsx
│   ├── toast-container.tsx   # Toast notifications
│   └── sw-register.tsx       # Service worker registration
├── contexts/
│   └── toast-context.tsx     # Global toast state
├── lib/
│   ├── providers/            # Twilio + Telnyx unified layer
│   ├── supabase/             # Client/server/middleware helpers
│   └── types/                # TypeScript definitions
├── middleware.ts              # Auth guard
mobile/                        # React Native (Expo)
├── app/                       # expo-router screens
│   ├── (tabs)/                # Inbox + Settings tabs
│   ├── chat/[id].tsx          # Chat screen
│   └── auth.tsx               # Login/register
├── lib/                       # Supabase, API client, notifications
└── eas.json                   # Expo EAS build profiles
electron/                      # Desktop app
├── main.ts                    # Window + tray + IPC
├── preload.ts                 # Renderer bridge
├── notifications.ts           # Supabase Realtime → OS notifications
├── updater.ts                 # Auto-updater
└── electron-builder.yml       # Build config
supabase/
└── migrations/                # 001_initial_schema + 002_unread_tracking

Outbound messages are stored as sent once the provider accepts them. Telnyx reports the carrier outcome later in message.finalized; smshub records it as delivered or failed with error_code / error_detail (for example 40010, "Not 10DLC registered") and the inbox shows the reason. Each Telnyx send sets webhook_url to /api/webhooks/telnyx, so this works even when the messaging profile has no webhook configured. Rows sent before that can be re-checked with bun scripts/telnyx-backfill-status.ts --dry-run (see the script header).

pnpm dev              # Start development server
pnpm build            # Production build
pnpm start            # Start production server
pnpm test             # Run unit and contract tests
pnpm test:e2e         # Run Playwright e2e tests
pnpm test:watch       # Run tests in watch mode
pnpm test:coverage    # Run tests with coverage
pnpm lint             # Lint source files
pnpm typecheck        # TypeScript type checking

Every commit automatically runs:

1. 🧪 Tests — vitest run
2. 🔍 Type check — tsc --noEmit
3. ✨ Lint — eslint --fix on staged .ts/.tsx files

Tables: providers, phone_numbers, contacts, conversations, messages

• Row Level Security (RLS) on all tables
• Realtime enabled on messages and conversations
• Unread tracking via last_read_at + computed count

See supabase/migrations/ for the full schema.

PRs welcome! Please ensure all checks pass before submitting:

pnpm test && pnpm test:e2e && pnpm typecheck && pnpm lint

MIT