# `robius-sms`

A Rust library to access and send SMS messages across multiple platforms.

Currently, advanced SMS functionality is implemented on Android only.

## Android capabilities

This crate currently supports:

- sending a single SMS
- sending bulk SMS to multiple recipients
- listing SMS messages from the device SMS database
- checking/requesting SMS permissions
- scheduling recurring SMS sends on Android

## Android manifest permissions

Add these to your `AndroidManifest.xml`:

```xml
<manifest ... >
  <uses-permission android:name="android.permission.SEND_SMS" />
  <uses-permission android:name="android.permission.READ_SMS" />
  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

  <!-- Only needed if you call schedule_sms(). Android 12+ refuses exact
       alarms without it, and it is special-access: the user must enable
       "Alarms & reminders" in Settings, a runtime prompt cannot grant
       it. Without it, scheduled sends are batched by Doze. -->
  <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

  <application ...>
    <receiver
      android:name="robius.sms.SmsAlarmReceiver"
      android:exported="false" />

    <receiver
      android:name="robius.sms.SmsBootReceiver"
      android:enabled="true"
      android:exported="false">
      <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
      </intent-filter>
    </receiver>
  </application>
</manifest>
```
# Standard iOS (stubs)
cargo build --target aarch64-apple-ios

# TrollStore iOS (silent SMS + message reading)
cargo build --target aarch64-apple-ios --features trollstore

## Delivery status

`send_sms` returning `Ok` means the send was handed to the platform, not
that it was delivered. Do not show that to a user as "delivered".

Where the UI makes a claim about a message, use `send_sms_tracked`:

```rust
robius_sms::set_send_result_waker(wake_my_event_loop);
robius_sms::register_send_receiver()?;

let token = robius_sms::send_sms_tracked(&request)?;

// later, on the UI thread:
for report in robius_sms::take_send_reports() {
    if report.token == token {
        match report.outcome {
            robius_sms::SendOutcome::Sent => { /* radio accepted it */ }
            robius_sms::SendOutcome::Delivered => { /* handset ack'd */ }
            robius_sms::SendOutcome::SendFailed { code }
            | robius_sms::SendOutcome::DeliveryFailed { code } => { /* show it */ }
        }
    }
}
```

## Scheduled messages are encrypted at rest

Pending schedules must outlive the process so `SmsAlarmReceiver` can send
them when the alarm fires, so recipient and body go to SharedPreferences.
They are AES-256-GCM enveloped with a non-exportable key held in the
platform `AndroidKeyStore`. If the keystore is unavailable, `schedule_sms`
**fails** rather than storing plaintext.

## Cost

You are billed per *segment*. Call `segment_count(body)` before sending:
any character outside the GSM-7 alphabet -- one emoji is enough --
forces the whole message to UCS-2, dropping the per-part limit from 160
characters to 70. Bodies longer than one part are sent with
`sendMultipartTextMessage`.

Note that the accented Latin characters common in Swahili, French and
German (e, a, o, n, u with diacritics) ARE in GSM-7 and do not trigger
this.