lfg-alarm 0.1.0__tar.gz

lfg_alarm-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+__pycache__/
+*.egg-info/
+.venv/

lfg_alarm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LFG Alarm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lfg_alarm-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: lfg-alarm
+Version: 0.1.0
+Summary: Ring a real alarm on a phone from code, and set alarms with LFG Alarm's tools.
+Project-URL: Homepage, https://lfg.gm/developers
+Project-URL: Source, https://github.com/lfg-gm/lfg-alarm-sdk
+Project-URL: Issues, https://github.com/lfg-gm/lfg-alarm-sdk/issues
+Author-email: LFG Alarm <support@lfg.gm>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,alarm,alert,mcp,notification,phone,webhook
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# lfg-alarm
+
+Ring a real alarm on a phone from code, and set alarms with [LFG Alarm](https://lfg.gm)'s tools.
+
+LFG Alarm is a social alarm clock for iPhone and Android. Rocco, LFG's agent, rings a real alarm on your phone, and your friends' phones, at a time or when something happens. This package lets a script, a cron job, a bot or an AI agent do the same.
+
+```bash
+pip install lfg-alarm
+```
+
+Python 3.8 or later. Standard library only, no dependencies.
+
+## Ring a phone when something happens
+
+Make a 🔮 **Anything alarm** in the LFG Alarm app (or with `set_webhook_alarm` below). It comes with a private link; calling it rings every phone on the alarm. No key needed: the link is the permission, so keep it secret.
+
+```python
+import os
+from lfg_alarm import ring
+
+result = ring(os.environ["LFG_RING_URL"])
+# RingResult(rang=True, woke_up=1, ...)
+# or rang=False with retry_after_seconds if it rang moments ago,
+# or rang=False with message="This alarm is switched off."
+```
+
+## Set alarms with a personal key
+
+Make a key in the LFG Alarm app: **Settings** > **AI apps and keys**. Pass it as `api_key`, or set `LFG_API_KEY`.
+
+```python
+from lfg_alarm import LfgAlarm
+
+lfg = LfgAlarm()  # reads LFG_API_KEY
+
+lfg.set_time_alarm(
+    "07:00",
+    "America/New_York",
+    repeat_days=["mon", "tue", "wed", "thu", "fri"],
+    title="Standup",
+    vibe="something upbeat",
+)
+
+hook = lfg.set_webhook_alarm("Deploy failed", quiet_for="5_min")
+print(hook.ring_url)
+
+print(lfg.list_alarms().text)
+```
+
+Every other tool works through `call`:
+
+```python
+lfg.call("set_price_alarm", token_id="solana", symbol="SOL", name="Solana", percent=10)
+tools = lfg.tools()  # all of them, with what each does
+```
+
+A tool that says no (a plan limit, a bad time) raises `LfgAlarmError` with LFG Alarm's own words.
+
+## What it talks to
+
+- `ring` calls the alarm's private link (`https://api.lfg.gm/horn/...`).
+- `LfgAlarm` calls LFG Alarm's hosted MCP server, `https://mcp.lfg.gm`: the same 33 tools Claude, ChatGPT and other AI apps use. AI apps can connect to it directly: [lfg.gm/agents](https://lfg.gm/agents).
+
+Some alarm types and limits depend on the account's plan. For plans and pricing, go to [lfg.gm](https://lfg.gm).
+
+[Developers](https://lfg.gm/developers) · [Support](https://lfg.gm/support) · [Privacy and terms](https://lfg.gm/legal) · MIT licence

lfg_alarm-0.1.0/README.md

@@ -0,0 +1,66 @@
+# lfg-alarm
+
+Ring a real alarm on a phone from code, and set alarms with [LFG Alarm](https://lfg.gm)'s tools.
+
+LFG Alarm is a social alarm clock for iPhone and Android. Rocco, LFG's agent, rings a real alarm on your phone, and your friends' phones, at a time or when something happens. This package lets a script, a cron job, a bot or an AI agent do the same.
+
+```bash
+pip install lfg-alarm
+```
+
+Python 3.8 or later. Standard library only, no dependencies.
+
+## Ring a phone when something happens
+
+Make a 🔮 **Anything alarm** in the LFG Alarm app (or with `set_webhook_alarm` below). It comes with a private link; calling it rings every phone on the alarm. No key needed: the link is the permission, so keep it secret.
+
+```python
+import os
+from lfg_alarm import ring
+
+result = ring(os.environ["LFG_RING_URL"])
+# RingResult(rang=True, woke_up=1, ...)
+# or rang=False with retry_after_seconds if it rang moments ago,
+# or rang=False with message="This alarm is switched off."
+```
+
+## Set alarms with a personal key
+
+Make a key in the LFG Alarm app: **Settings** > **AI apps and keys**. Pass it as `api_key`, or set `LFG_API_KEY`.
+
+```python
+from lfg_alarm import LfgAlarm
+
+lfg = LfgAlarm()  # reads LFG_API_KEY
+
+lfg.set_time_alarm(
+    "07:00",
+    "America/New_York",
+    repeat_days=["mon", "tue", "wed", "thu", "fri"],
+    title="Standup",
+    vibe="something upbeat",
+)
+
+hook = lfg.set_webhook_alarm("Deploy failed", quiet_for="5_min")
+print(hook.ring_url)
+
+print(lfg.list_alarms().text)
+```
+
+Every other tool works through `call`:
+
+```python
+lfg.call("set_price_alarm", token_id="solana", symbol="SOL", name="Solana", percent=10)
+tools = lfg.tools()  # all of them, with what each does
+```
+
+A tool that says no (a plan limit, a bad time) raises `LfgAlarmError` with LFG Alarm's own words.
+
+## What it talks to
+
+- `ring` calls the alarm's private link (`https://api.lfg.gm/horn/...`).
+- `LfgAlarm` calls LFG Alarm's hosted MCP server, `https://mcp.lfg.gm`: the same 33 tools Claude, ChatGPT and other AI apps use. AI apps can connect to it directly: [lfg.gm/agents](https://lfg.gm/agents).
+
+Some alarm types and limits depend on the account's plan. For plans and pricing, go to [lfg.gm](https://lfg.gm).
+
+[Developers](https://lfg.gm/developers) · [Support](https://lfg.gm/support) · [Privacy and terms](https://lfg.gm/legal) · MIT licence

lfg_alarm-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lfg-alarm"
+version = "0.1.0"
+description = "Ring a real alarm on a phone from code, and set alarms with LFG Alarm's tools."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.8"
+authors = [{ name = "LFG Alarm", email = "support@lfg.gm" }]
+keywords = ["alarm", "alert", "notification", "phone", "webhook", "mcp", "ai-agent"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Communications",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://lfg.gm/developers"
+Source = "https://github.com/lfg-gm/lfg-alarm-sdk"
+Issues = "https://github.com/lfg-gm/lfg-alarm-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lfg_alarm"]

lfg_alarm-0.1.0/src/lfg_alarm/__init__.py

@@ -0,0 +1,183 @@
+"""LFG Alarm for Python: ring a real alarm on a phone from code, and set alarms
+with a personal key.
+
+Two ways in:
+
+- ``ring(url)`` calls an Anything alarm's private link. No key needed: the link
+  is the permission. Make the alarm in the LFG Alarm app, or with
+  ``LfgAlarm.set_webhook_alarm``.
+- ``LfgAlarm(api_key=...)`` uses LFG Alarm's hosted MCP server
+  (https://mcp.lfg.gm), the same tools Claude and ChatGPT use. Make a key in the
+  LFG Alarm app: Settings > AI apps and keys.
+
+Standard library only.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+__all__ = ["DEFAULT_BASE_URL", "LfgAlarm", "LfgAlarmError", "RingResult", "ToolResult", "ring"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://mcp.lfg.gm"
+_USER_AGENT = f"lfg-alarm-python/{__version__}"
+
+
+class LfgAlarmError(Exception):
+    """Something LFG Alarm said no to, or could not be reached for."""
+
+    def __init__(self, message: str, status: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+@dataclass
+class RingResult:
+    rang: bool
+    """True when the alarm rang."""
+    woke_up: Optional[int] = None
+    """How many people's phones it rang on."""
+    retry_after_seconds: Optional[int] = None
+    """When it rang moments ago: seconds until it can ring again."""
+    message: Optional[str] = None
+    """LFG Alarm's own words when it did not ring."""
+
+
+@dataclass
+class ToolResult:
+    text: str
+    """The tool's answer, in plain words."""
+    data: Any = None
+    """The tool's structured answer, when it gives one (for example the alarm)."""
+    ring_url: Optional[str] = None
+    """For a webhook alarm: the private link that rings it (pass it to ``ring``)."""
+
+
+def _post(url: str, body: bytes, headers: Dict[str, str], timeout: float):
+    req = urllib.request.Request(url, data=body, method="POST")
+    req.add_header("User-Agent", _USER_AGENT)
+    for k, v in headers.items():
+        req.add_header(k, v)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return res.status, dict(res.headers), res.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        return e.code, dict(e.headers or {}), e.read().decode("utf-8", "replace")
+
+
+def ring(url: str, timeout: float = 15) -> RingResult:
+    """Rings an Anything alarm by calling its private link (https://api.lfg.gm/horn/...).
+
+    Returns ``RingResult(rang=False, ...)`` with the reason when the alarm is
+    cooling down or switched off; raises ``LfgAlarmError`` when the link is not
+    an alarm's.
+    """
+    # An empty JSON body: the link never reads it, and urllib would otherwise label it a form, which the server refuses.
+    status, headers, raw = _post(url, b"{}", {"Content-Type": "application/json"}, timeout)
+    try:
+        body = json.loads(raw) if raw else {}
+    except ValueError:
+        body = {}
+    if 200 <= status < 300:
+        return RingResult(rang=True, woke_up=body.get("wokeUp"))
+    if status == 429:
+        after = body.get("retryAfterSeconds") or int({k.lower(): v for k, v in headers.items()}.get("retry-after", 60))
+        return RingResult(rang=False, retry_after_seconds=after, message=body.get("message"))
+    if status == 409:
+        return RingResult(rang=False, message=body.get("message") or "This alarm is switched off.")
+    raise LfgAlarmError(body.get("message") or f"LFG Alarm answered {status}", status)
+
+
+def _snake(args: Dict[str, Any]) -> Dict[str, Any]:
+    """timeZone -> time_zone; snake_case passes through. None values are left out."""
+    return {re.sub(r"[A-Z]", lambda m: "_" + m.group(0).lower(), k): v for k, v in args.items() if v is not None}
+
+
+class LfgAlarm:
+    """A client for LFG Alarm's tools. ``api_key`` defaults to the LFG_API_KEY environment variable."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, timeout: float = 30) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("LFG_API_KEY")
+        self.base_url = base_url
+        self.timeout = timeout
+        self._ids = itertools.count(1)
+
+    def _rpc(self, method: str, params: Dict[str, Any]) -> Any:
+        if not self.api_key:
+            raise LfgAlarmError(
+                "No API key. Make one in the LFG Alarm app (Settings > AI apps and keys) "
+                "and pass it as api_key, or set LFG_API_KEY."
+            )
+        payload = json.dumps({"jsonrpc": "2.0", "id": next(self._ids), "method": method, "params": params}).encode()
+        status, headers, raw = _post(
+            self.base_url,
+            payload,
+            {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json, text/event-stream",
+            },
+            self.timeout,
+        )
+        if status == 401:
+            raise LfgAlarmError("LFG Alarm did not accept that API key. Make a new one in Settings > AI apps and keys.", 401)
+        if not 200 <= status < 300:
+            raise LfgAlarmError(f"LFG Alarm answered {status}", status)
+        content_type = {k.lower(): v for k, v in headers.items()}.get("content-type", "")
+        if "text/event-stream" in content_type:
+            # A server may answer as a one-message event stream.
+            lines = [line[5:].strip() for line in raw.splitlines() if line.startswith("data:")]
+            raw = lines[-1] if lines else "{}"
+        msg = json.loads(raw or "{}")
+        if msg.get("error"):
+            raise LfgAlarmError(msg["error"].get("message") or "LFG Alarm could not do that.")
+        return msg.get("result")
+
+    def call(self, tool: str, **args: Any) -> ToolResult:
+        """Calls any of LFG Alarm's tools by name ("set_price_alarm"), with its arguments."""
+        result = self._rpc("tools/call", {"name": tool, "arguments": _snake(args)}) or {}
+        text = "\n".join(c.get("text", "") for c in result.get("content", []) if c.get("type") == "text")
+        if result.get("isError"):
+            raise LfgAlarmError(text or "LFG Alarm could not do that.")
+        return ToolResult(text=text, data=result.get("structuredContent"))
+
+    def tools(self) -> List[Dict[str, Any]]:
+        """Every tool there is, with what it does."""
+        result = self._rpc("tools/list", {}) or {}
+        return [{k: t.get(k) for k in ("name", "title", "description")} for t in result.get("tools", [])]
+
+    def set_time_alarm(
+        self,
+        time: str,
+        time_zone: str,
+        date: Optional[str] = None,
+        repeat_days: Optional[List[str]] = None,
+        title: Optional[str] = None,
+        vibe: Optional[str] = None,
+        **more: Any,
+    ) -> ToolResult:
+        """A time alarm: "07:00" in an IANA time zone, once (date) or on repeat days (["mon", "fri"])."""
+        return self.call(
+            "set_time_alarm", time=time, time_zone=time_zone, date=date, repeat_days=repeat_days, title=title, vibe=vibe, **more
+        )
+
+    def set_webhook_alarm(self, title: str, quiet_for: Optional[str] = None, **more: Any) -> ToolResult:
+        """An Anything alarm, with the private link that rings it as ``ring_url``."""
+        result = self.call("set_webhook_alarm", title=title, quiet_for=quiet_for, **more)
+        match = re.search(r"https://\S+/horn/[A-Za-z0-9]+", result.text)
+        result.ring_url = match.group(0) if match else None
+        return result
+
+    def list_alarms(self) -> ToolResult:
+        return self.call("list_my_alarms")
+
+    def delete_alarm(self, id: str) -> ToolResult:
+        return self.call("delete_alarm", id=id)

lfg_alarm-0.1.0/tests/test_lfg_alarm.py

@@ -0,0 +1,83 @@
+import json
+import unittest
+from unittest import mock
+
+import lfg_alarm
+from lfg_alarm import LfgAlarm, LfgAlarmError, ring
+
+
+def answer(status, body, headers=None):
+    raw = body if isinstance(body, str) else json.dumps(body)
+    return status, headers or {"Content-Type": "application/json"}, raw
+
+
+class RingTests(unittest.TestCase):
+    def test_rang(self):
+        with mock.patch.object(lfg_alarm, "_post", return_value=answer(200, {"fired": True, "wokeUp": 2})):
+            r = ring("https://api.lfg.gm/horn/abc")
+        self.assertTrue(r.rang)
+        self.assertEqual(r.woke_up, 2)
+
+    def test_cooling_down_is_not_an_error(self):
+        with mock.patch.object(lfg_alarm, "_post", return_value=answer(429, {"message": "Wait", "retryAfterSeconds": 42})):
+            r = ring("https://api.lfg.gm/horn/abc")
+        self.assertFalse(r.rang)
+        self.assertEqual(r.retry_after_seconds, 42)
+
+    def test_switched_off(self):
+        with mock.patch.object(lfg_alarm, "_post", return_value=answer(409, {"message": "This alarm is switched off."})):
+            r = ring("https://api.lfg.gm/horn/abc")
+        self.assertFalse(r.rang)
+        self.assertEqual(r.message, "This alarm is switched off.")
+
+    def test_not_an_alarm_link_raises(self):
+        with mock.patch.object(lfg_alarm, "_post", return_value=answer(404, {"message": "No such horn"})):
+            with self.assertRaises(LfgAlarmError):
+                ring("https://api.lfg.gm/horn/nope")
+
+
+class ClientTests(unittest.TestCase):
+    def test_call_sends_snake_case_and_the_key(self):
+        sent = {}
+
+        def fake(url, body, headers, timeout):
+            sent.update(url=url, body=json.loads(body), headers=headers)
+            return answer(200, {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "Set."}], "structuredContent": {"alarm": {"id": "a1"}}}})
+
+        with mock.patch.object(lfg_alarm, "_post", side_effect=fake):
+            r = LfgAlarm(api_key="lfg_pat_test").set_time_alarm("07:00", "America/New_York", repeat_days=["mon"])
+        self.assertEqual(sent["url"], "https://mcp.lfg.gm")
+        self.assertEqual(sent["headers"]["Authorization"], "Bearer lfg_pat_test")
+        self.assertEqual(sent["body"]["params"], {"name": "set_time_alarm", "arguments": {"time": "07:00", "time_zone": "America/New_York", "repeat_days": ["mon"]}})
+        self.assertEqual(r.text, "Set.")
+        self.assertEqual(r.data, {"alarm": {"id": "a1"}})
+
+    def test_refusal_raises_with_its_words(self):
+        with mock.patch.object(lfg_alarm, "_post", return_value=answer(200, {"jsonrpc": "2.0", "id": 1, "result": {"isError": True, "content": [{"type": "text", "text": "Needs a paid plan."}]}})):
+            with self.assertRaisesRegex(LfgAlarmError, "Needs a paid plan"):
+                LfgAlarm(api_key="k").list_alarms()
+
+    def test_event_stream_answer(self):
+        stream = 'event: message\ndata: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"ok"}]}}\n\n'
+        with mock.patch.object(lfg_alarm, "_post", return_value=answer(200, stream, {"Content-Type": "text/event-stream"})):
+            self.assertEqual(LfgAlarm(api_key="k").list_alarms().text, "ok")
+
+    def test_webhook_alarm_returns_the_ring_link(self):
+        text = "Address to call (a POST request rings it): https://api.lfg.gm/horn/abc123\nMore"
+        with mock.patch.object(lfg_alarm, "_post", return_value=answer(200, {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": text}]}})):
+            self.assertEqual(LfgAlarm(api_key="k").set_webhook_alarm("Deploy failed").ring_url, "https://api.lfg.gm/horn/abc123")
+
+    def test_no_key_says_where_to_get_one(self):
+        with mock.patch.dict("os.environ", {}, clear=True):
+            with self.assertRaisesRegex(LfgAlarmError, "AI apps and keys"):
+                LfgAlarm().list_alarms()
+
+    def test_refused_key(self):
+        with mock.patch.object(lfg_alarm, "_post", return_value=answer(401, {"error": "unauthorized"})):
+            with self.assertRaises(LfgAlarmError) as e:
+                LfgAlarm(api_key="bad").list_alarms()
+        self.assertEqual(e.exception.status, 401)
+
+
+if __name__ == "__main__":
+    unittest.main()