Metadata-Version: 2.4
Name: gsm-sms
Version: 0.1.0
Summary: Async Python library for direct ownership of a GSM SMS modem
Project-URL: Homepage, https://github.com/jag-k/gsm-sms
Project-URL: Repository, https://github.com/jag-k/gsm-sms.git
Project-URL: Issues, https://github.com/jag-k/gsm-sms/issues
Author-email: jag_k <30597878+jag-k@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: pydantic>=2.12
Requires-Dist: pyserial-asyncio>=0.6
Requires-Dist: pyserial>=3.5
Requires-Dist: python-messaging>=0.5.13
Provides-Extra: client
Requires-Dist: httpx-sse==0.4.*; extra == 'client'
Requires-Dist: httpx>=0.28; extra == 'client'
Description-Content-Type: text/markdown

# gsm-sms

Async Python library that exclusively owns a GSM modem serial port. It
serializes AT commands, decodes text/PDU and multipart SMS, emits typed events,
and deletes incoming messages only after `ack_incoming()`.

```python
from gsm_sms.core.events import IncomingSmsEvent
from gsm_sms.core.modem import GsmSms

modem = GsmSms(port="/dev/ttyUSB0")
await modem.start()

async for event in modem.events():
    if isinstance(event, IncomingSmsEvent):
        await deliver(event.message)
        await modem.ack_incoming(event.message.id)
```

Install the library with `pip install gsm-sms`. Applications that talk to a
gateway instead of opening the modem use `pip install "gsm-sms[client]"` and
`gsm_sms.client.GatewayClient`.

## Gateway with Docker Compose

The gateway is a separate, Docker-only REST/SSE service. It persists events and
send operations in SQLite, supports resumable SSE cursors, and must remain the
only process using the modem.

```yaml
services:
  gateway:
    image: ghcr.io/jag-k/gsm-sms-gateway:latest
    restart: unless-stopped
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    environment:
      MODEM__SERIAL_PORT: /dev/ttyUSB0
      MODEM__BAUD_RATE: "115200"
      MODEM__SMS_STORAGE: SM
      JOURNAL__DATABASE_PATH: /data/gateway.sqlite3
    volumes:
      - ./data:/data
    ports:
      - 127.0.0.1:8000:8000
    networks:
      - gsm-sms

networks:
  gsm-sms:
    name: gsm-sms-network
```

```bash
docker compose up -d
curl http://127.0.0.1:8000/v1/health
```

For all environment variables, see
[`docs/gateway/Configuration.md`](docs/gateway/Configuration.md). The published
Python package intentionally excludes FastAPI, Docker, Telegram, and Matrix.
