Metadata-Version: 2.4
Name: imessage-wrapper
Version: 0.1.0
Summary: Sync-first Python API for local macOS Messages and Contacts
Author: imessage-wrapper contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/kylevedder/imessage-wrapper
Project-URL: Repository, https://github.com/kylevedder/imessage-wrapper
Project-URL: Issues, https://github.com/kylevedder/imessage-wrapper/issues
Project-URL: Source, https://github.com/kylevedder/imessage-wrapper
Keywords: imessage,messages,macos,contacts,sms
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: phonenumbers>=8.13
Provides-Extra: contacts
Requires-Dist: pyobjc-framework-Contacts>=10.0; sys_platform == "darwin" and extra == "contacts"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# imessage-wrapper

`imessage-wrapper` is a sync-first Python package for reading local macOS
Messages history, enriching it with macOS Contacts, sending through Messages.app,
and creating/updating Contacts records through Apple's Contacts framework.

## Install

```bash
pip install imessage-wrapper
```

Install the optional Contacts write dependency on macOS with:

```bash
pip install "imessage-wrapper[contacts]"
```

## Usage

```python
from imessage_wrapper import IMessageClient

client = IMessageClient()

for chat in client.chats(limit=10):
    print(chat.id, chat.name, chat.last_message_at)

messages = client.messages(chat_id=chat.id, limit=50, attachments=True)
client.send(chat_id=chat.id, text="hello")
```

## Permissions

Reads require Full Disk Access for the Python process so it can open
`~/Library/Messages/chat.db` and the AddressBook databases. Sending requires
Automation permission to control Messages.app. Contact writes require Contacts
permission and the `pyobjc-framework-Contacts` dependency on macOS.

The package reads Messages and AddressBook SQLite databases in read-only mode.
It never writes those databases directly.
