Skip to content

Send and receive SMS messages using your Android phone programmatically via a simple HTTP API

MCP related fixes

Acho Arnold8f17198607c0
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000..dd234131
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,141 @@
+# Copilot Instructions for httpSMS
+
+httpSMS is a service that turns an Android phone into an SMS gateway via an HTTP API. This is a monorepo with three components:
+
+- **`api/`** — Go backend (Fiber, GORM, PostgreSQL)
+- **`web/`** — Nuxt 2 frontend (Vue 2, Vuetify 2, TypeScript)
+- **`android/`** — Native Android app (Kotlin)
+
+## Build, Test, and Lint Commands
+
+### API (Go)
+
+```bash
+cd api
+
+# Development with hot-reload
+air
+
+# Build
+go build -o ./tmp/main.exe .
+
+# Run tests
+go test ./...
+
+# Run a single test
+go test ./pkg/services/ -run TestMessageService
+
+# Generate Swagger docs (required after changing API annotations)
+swag init --requiredByDefault --parseDependency --parseInternal
+
+# Pre-commit hooks run: go-fumpt, go-imports, go-lint, go-mod-tidy
+```
+
+### Web (Nuxt/Vue)
+
+```bash
+cd web
+
+# Install dependencies
+pnpm install
+
+# Development server (port 3000)
+pnpm dev
+
+# Lint (eslint + stylelint + prettier)
+pnpm lint
+
+# Auto-fix lint issues
+pnpm lintfix
+
+# Run tests (Jest)
+pnpm test
+
+# Static site generation (production build)
+pnpm run generate
+
+# Regenerate TypeScript API models from Swagger
+pnpm api:models
+```
+
+### Android (Kotlin)
+
+```bash
+cd android
+
+# Build
+./gradlew build
+
+# Debug APK
+./gradlew assembleDebug
+
+# Release APK
+./gradlew assembleRelease
+```
+
+### Docker (full stack)
+
+```bash
+# Start all services (PostgreSQL, Redis, API, Web)
+docker compose up --build
+# API at localhost:8000, Web at localhost:3000
+```
+
+## Architecture
+
+### API — Layered Architecture with Event-Driven Processing
+
+The API uses a **DI container** (`pkg/di/container.go`) that lazily initializes all services as singletons. The layered architecture flows as:
+
+**Handlers → Services → Repositories → GORM/PostgreSQL**
+
+- **Handlers** (`pkg/handlers/`) — Fiber HTTP handlers. Each has a `RegisterRoutes()` method and embeds a base `handler` struct with standardized response methods (`responseBadRequest`, `responseNotFound`, etc.).
+- **Services** (`pkg/services/`) — Business logic. Orchestrate repositories and dispatch events.
+- **Repositories** (`pkg/repositories/`) — Data access via GORM. Interfaces defined alongside GORM implementations (prefixed `gorm*`).
+- **Validators** (`pkg/validators/`) — One validator per handler, return `url.Values` for field errors.
+- **Entities** (`pkg/entities/`) — Domain models, auto-migrated by GORM.
+
+**Event system**: Uses CloudEvents spec (`cloudevents/sdk-go`). Events defined in `pkg/events/` (31 event types). Listeners in `pkg/listeners/` process events either synchronously or via Google Cloud Tasks queue (emulator mode for local dev).
+
+**Entry point**: `main.go` loads `.env` in local mode, creates the DI container, and starts Fiber on `APP_PORT`.
+
+### Web — Nuxt 2 Static SPA
+
+- **State management**: Single Vuex store (`store/index.ts`) — actions make API calls via Axios, mutations update state, getters expose computed values.
+- **Components**: Use `vue-property-decorator` class syntax with `@Component`, `@Prop`, `@Watch` decorators.
+- **API client**: Axios configured in `plugins/axios.ts` with Firebase bearer token auth and `x-api-key` header support.
+- **API models**: TypeScript types in `models/` are auto-generated from the Swagger spec via `swagger-typescript-api`.
+- **Auth**: Firebase Authentication (Email/Password, Google, GitHub) with `auth` and `guest` middleware for route guards.
+- **Real-time**: Pusher.js for live message updates.
+
+### Android — Task-Oriented, Event-Driven
+
+- **No MVVM/Clean Architecture** — uses a flat package structure with Activities, Services, BroadcastReceivers, and WorkManager tasks.
+- **FCM integration**: `MyFirebaseMessagingService` receives push notifications → schedules `SendSmsWorker` via WorkManager → fetches message from API → sends SMS.
+- **Dual SIM support**: Independent settings per SIM via `Settings` singleton (SharedPreferences).
+- **HTTP client**: OkHttp with `x-api-key` authentication against the API.
+- **Encryption**: AES-256/CFB with SHA-256 key derivation (`Encrypter.kt`).
+
+## Key Conventions
+
+### API (Go)
+
+- **Error handling**: Use `github.com/palantir/stacktrace` — wrap errors with `stacktrace.Propagate(err, "context")` or `stacktrace.PropagateWithCode()`. Never return bare errors.
+- **Database queries**: Always use GORM query builder with context propagation (`repository.db.WithContext(ctx)`). No raw SQL.
+- **Route registration**: Each handler defines `RegisterRoutes()` called from the DI container. Routes follow REST conventions under `/v1/`.
+- **Middleware chain**: HTTP Logger → OpenTelemetry → CORS → Request Logger → Bearer Auth → API Key Auth.
+- **Observability**: All layers are instrumented with OpenTelemetry (Fiber, GORM, Redis). Pass `logger` and `tracer` to constructors.
+- **Code formatting**: `go-fumpt` (not `gofmt`), enforced via pre-commit hooks.
+
+### Web (Vue/TypeScript)
+
+- **Formatting**: No semicolons, single quotes, 2-space indentation (Prettier + ESLint).
+- **Component style**: Class-based with `vue-property-decorator`, not Options API (though some pages use `Vue.extend()`).
+- **Store pattern**: Actions handle async API calls and commit mutations. Access store from components via `this.$store`.
+
+### Android (Kotlin)
+
+- **API calls**: Use `HttpSmsApiService` singleton (static `create()` factory). OkHttp client with `x-api-key` header.
+- **Background work**: Use WorkManager for tasks that must survive process death. Direct `Thread { }` for lightweight background ops.
+- **State**: `Settings` object (SharedPreferences singleton) for all persistent state.
+- **Phone number formatting**: Use `libphonenumber` for E.164 format validation.
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 00000000..da367af6
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,17 @@
+{
+ "mcpServers": {
+ "playwright": {
+ "type": "stdio",
+ "command": "npx",
+ "args": [
+ "-y",
+ "@modelcontextprotocol/server-playwright",
+ "--base-url",
+ "http://localhost:3000"
+ ],
+ "env": {
+ "BROWSER": "chromium"
+ }
+ }
+ }
+}
diff --git a/android/app/build.gradle b/android/app/build.gradle
index 4436e272..b64e834f 100644
--- a/android/app/build.gradle
+++ b/android/app/build.gradle
@@ -10,7 +10,7 @@ def gitHash = providers.exec {
}.standardOutput.asText.map { it.trim() }.getOrElse("unknown")
android {
- compileSdk 36
+ compileSdk = 36
defaultConfig {
applicationId "com.httpsms"
@@ -46,24 +46,24 @@ android {
}
dependencies {
- implementation platform('com.google.firebase:firebase-bom:33.13.0')
+ implementation platform('com.google.firebase:firebase-bom:34.11.0')
implementation 'com.journeyapps:zxing-android-embedded:4.3.0'
implementation 'com.google.firebase:firebase-analytics-ktx'
implementation 'com.google.firebase:firebase-messaging-ktx'
- implementation 'com.squareup.okhttp3:okhttp:4.12.0'
+ implementation 'com.squareup.okhttp3:okhttp:5.3.2'
implementation 'com.jakewharton.timber:timber:5.0.1'
implementation 'androidx.preference:preference-ktx:1.2.1'
- implementation 'androidx.work:work-runtime-ktx:2.10.1'
- implementation 'androidx.core:core-ktx:1.16.0'
+ implementation 'androidx.work:work-runtime-ktx:2.11.1'
+ implementation 'androidx.core:core-ktx:1.18.0'
implementation "androidx.cardview:cardview:1.0.0"
implementation 'com.beust:klaxon:5.6'
- implementation 'androidx.appcompat:appcompat:1.7.0'
- implementation 'org.apache.commons:commons-text:1.12.0'
- implementation 'com.google.android.material:material:1.12.0'
+ implementation 'androidx.appcompat:appcompat:1.7.1'
+ implementation 'org.apache.commons:commons-text:1.15.0'
+ implementation 'com.google.android.material:material:1.13.0'
implementation 'androidx.constraintlayout:constraintlayout:2.2.1'
- implementation 'com.googlecode.libphonenumber:libphonenumber:9.0.4'
+ implementation 'com.googlecode.libphonenumber:libphonenumber:9.0.26'
implementation 'com.klinkerapps:android-smsmms:5.2.6'
testImplementation 'junit:junit:4.13.2'
- androidTestImplementation 'androidx.test.ext:junit:1.2.1'
- androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
+ androidTestImplementation 'androidx.test.ext:junit:1.3.0'
+ androidTestImplementation 'androidx.test.espresso:espresso-core:3.7.0'
}
diff --git a/android/app/src/main/AndroidManifest.xml b/android/app/src/main/AndroidManifest.xml
index 409b7140..54fa35c8 100644
--- a/android/app/src/main/AndroidManifest.xml
+++ b/android/app/src/main/AndroidManifest.xml
@@ -12,6 +12,7 @@
<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.SEND_SMS" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
+ <uses-permission android:name="android.permission.RECEIVE_MMS"/>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
diff --git a/api/pkg/handlers/user_handler.go b/api/pkg/handlers/user_handler.go
index 2d3895da..d63046dc 100644
--- a/api/pkg/handlers/user_handler.go
+++ b/api/pkg/handlers/user_handler.go
@@ -307,12 +307,13 @@ func (h *UserHandler) subscriptionPayments(c *fiber.Ctx) error {
// @Tags Users
// @Accept json
// @Produce application/pdf
-// @Param payload body requests.UserPaymentInvoice true "Generate subscription payment invoice parameters"
-// @Success 200 {file} file
-// @Failure 400 {object} responses.BadRequest
-// @Failure 401 {object} responses.Unauthorized
-// @Failure 422 {object} responses.UnprocessableEntity
-// @Failure 500 {object} responses.InternalServerError
+// @Param payload body requests.UserPaymentInvoice true "Generate subscription payment invoice parameters"
+// @Param subscriptionInvoiceID path string true "ID of the subscription invoice to generate the PDF for"
+// @Success 200 {file} file
+// @Failure 400 {object} responses.BadRequest
+// @Failure 401 {object} responses.Unauthorized
+// @Failure 422 {object} responses.UnprocessableEntity
+// @Failure 500 {object} responses.InternalServerError
// @Router /users/subscription/invoices/{subscriptionInvoiceID} [post]
func (h *UserHandler) subscriptionInvoice(c *fiber.Ctx) error {
ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)
diff --git a/api/pkg/requests/message_send_request.go b/api/pkg/requests/message_send_request.go
index 1a1d6830..d40f0f88 100644
--- a/api/pkg/requests/message_send_request.go
+++ b/api/pkg/requests/message_send_request.go
@@ -14,9 +14,11 @@ import (
// MessageSend is the payload for sending and SMS message
type MessageSend struct {
request
- From string `json:"from" example:"+18005550199"`
- To string `json:"to" example:"+18005550100"`
- Content string `json:"content" example:"This is a sample text message"`
+ From string `json:"from" example:"+18005550199"`
+ To string `json:"to" example:"+18005550100"`
+ Content string `json:"content" example:"This is a sample text message"`
+
+ // Attachments are optional. When you provide a list of attachments, the message will be sent out as an MMS
Attachments []entities.MessageAttachment `json:"attachments" validate:"optional"`
// Encrypted is an optional parameter used to determine if the content is end-to-end encrypted. Make sure to set the encryption key on the httpSMS mobile app