notamify-sdk 0.1.0__tar.gz

notamify_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skymerse Inc. (Notamify)
+
+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.

notamify_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include examples *.md *.py

notamify_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: notamify-sdk
+Version: 0.1.0
+Summary: Python SDK for Notamify APIs
+Author: Damian Szumski
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/skymerse/notamify-sdk-python
+Project-URL: Repository, https://github.com/skymerse/notamify-sdk-python
+Project-URL: Issues, https://github.com/skymerse/notamify-sdk-python/issues
+Keywords: notam,aviation,webhook,sdk
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2
+Dynamic: license-file
+
+# notamify-sdk (Python)
+
+Python SDK for Notamify public APIs:
+
+- Notamify API v2 (`https://api.notamify.com/api/v2`)
+- Watcher API (`https://watcher.notamify.com`)
+
+## Features
+
+- Typed API client with one auth token
+- Pydantic response/request models
+- Pager-style NOTAM listing via `client.notams.*` with item iteration and `pager.pages`
+- Supported NOTAM endpoints:
+  - `GET /notams`
+  - `GET /notams/raw`
+  - `GET /notams/nearby`
+  - `GET /notams/archive`
+  - `POST /notams/briefing`
+  - `GET /notams/briefing/{uuid}`
+  - `POST /notams/prioritisation`
+- Watcher listener management + webhook logs/secrets
+- Listener `mode` support (`prod` default, `sandbox` for test-only listeners)
+- Listener lifecycle support via `lifecycle.enabled` and `lifecycle.types`
+- Sandbox test delivery endpoint (`POST /listeners/{id}/sandbox:send`)
+- Webhook signature verification (`X-Notamify-Signature`)
+- Typed webhook event models for `interpretation` and `lifecycle` payloads
+- Embedded receiver + cloudflared helper for local webhook testing
+- Strict receiver mode fails fast when webhook secret is missing
+
+## Install
+
+```bash
+pip install notamify-sdk
+```
+
+Or with `uv`:
+
+```bash
+uv add notamify-sdk
+```
+
+For contributors working from a source checkout:
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Environment variables (highest priority):
+
+- `NOTAMIFY_TOKEN`
+- `NOTAMIFY_API_BASE_URL`
+- `NOTAMIFY_WATCHER_BASE_URL`
+- `NOTAMIFY_WEBHOOK_SECRET`
+- `NOTAMIFY_CONFIG_FILE`
+
+Default config file: `~/.config/notamify/config.json`
+
+## Usage
+
+```python
+from notamify_sdk import NotamifyClient
+
+client = NotamifyClient(token="YOUR_TOKEN")
+
+# The API accepts at most 30 items per page.
+active_notams = list(client.notams.active({
+    "location": ["KJFK", "KLAX"],
+    "per_page": 30,
+}))
+print(len(active_notams))
+
+first_page = next(iter(client.notams.active({
+    "location": ["KJFK", "KLAX"],
+    "per_page": 30,
+}).pages))
+print(first_page.total_count)
+
+job = client.create_async_briefing({
+    "locations": [{
+        "location": "KJFK",
+        "type": "origin",
+        "starts_at": "2026-02-25T10:00:00Z",
+        "ends_at": "2026-02-25T12:00:00Z",
+    }],
+})
+print(job.uuid)
+
+# Watcher sandbox flow
+listener = client.create_listener(
+    "https://example.trycloudflare.com/webhooks/notamify",
+    mode="sandbox",
+    lifecycle={"enabled": False},
+)
+print(listener.webhook_secret)
+sandbox_result = client.send_sandbox_message(listener.id, "SANDBOX-NOTAM-1")
+print(sandbox_result.notam_id)
+```
+
+## Pagination
+
+The SDK exposes two NOTAM access styles:
+
+- `client.get_active_notams(...)`, `client.get_raw_notams(...)`, `client.get_nearby_notams(...)`, and `client.get_historical_notams(...)` return a single `NotamListResult` page.
+- `client.notams.active(...)`, `client.notams.raw(...)`, `client.notams.nearby(...)`, and `client.notams.historical(...)` return a pager that fetches all pages lazily as you iterate.
+
+Use the pager when you want all NOTAMs across pages:
+
+```python
+pager = client.notams.active(
+    {"location": ["KJFK", "KLAX"]},
+    per_page=30,
+)
+
+for notam in pager:
+    print(notam.id)
+```
+
+If you want everything in memory at once, materialize the pager with `list(...)`:
+
+```python
+all_notams = list(
+    client.notams.active(
+        {"location": ["KJFK", "KLAX"]},
+        per_page=30,
+    )
+)
+```
+
+If you need page metadata such as `page`, `per_page`, or `total_count`, iterate over `pager.pages`:
+
+```python
+pager = client.notams.active(
+    {"location": ["KJFK", "KLAX"]},
+    per_page=30,
+)
+
+for page in pager.pages:
+    print(page.page, page.total_count, len(page.notams))
+```
+
+The API allows at most `30` items per page. The SDK validates this with Pydantic and rejects larger `per_page` values.
+
+## Local Webhook Testing
+
+The example scripts live in the repository and source distribution under `examples/`.
+They are intended to be run from a source checkout or source distribution, not from an installed wheel alone.
+
+- Production: implement the webhook endpoint in your own application code.
+- Verify `X-Notamify-Signature` using `NOTAMIFY_WEBHOOK_SECRET`.
+- Production watcher deliveries include `kind`, `event_id`, and `notam`.
+- Lifecycle watcher deliveries also include `change.changed_notam_id` for the original NOTAM that was cancelled or replaced.
+- Local development: expose your local app endpoint with `cloudflared`, then set watcher `webhook_url` to that tunnel URL.
+- Sandbox test sends use the same webhook payload DTO as production sends, with mock NOTAM content.
+
+Prerequisite: `cloudflared` must be installed and available in `PATH`.
+
+```bash
+export NOTAMIFY_TOKEN="your_notamify_token"
+export LOCAL_APP_URL="http://127.0.0.1:8080/webhooks/notamify"
+uv run python ./examples/local_service_run.py
+```
+
+## Examples
+
+- `examples/service_receiver.py`: minimal production-style webhook receiver
+- `examples/local_service_run.py`: cloudflared tunnel + sandbox delivery flow
+- `examples/notams_fetch.py`: straightforward NOTAM query examples
+- `examples/README.md`: setup notes and sample payloads
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_*.py'
+```
+
+## License
+
+MIT

notamify_sdk-0.1.0/README.md

@@ -0,0 +1,180 @@
+# notamify-sdk (Python)
+
+Python SDK for Notamify public APIs:
+
+- Notamify API v2 (`https://api.notamify.com/api/v2`)
+- Watcher API (`https://watcher.notamify.com`)
+
+## Features
+
+- Typed API client with one auth token
+- Pydantic response/request models
+- Pager-style NOTAM listing via `client.notams.*` with item iteration and `pager.pages`
+- Supported NOTAM endpoints:
+  - `GET /notams`
+  - `GET /notams/raw`
+  - `GET /notams/nearby`
+  - `GET /notams/archive`
+  - `POST /notams/briefing`
+  - `GET /notams/briefing/{uuid}`
+  - `POST /notams/prioritisation`
+- Watcher listener management + webhook logs/secrets
+- Listener `mode` support (`prod` default, `sandbox` for test-only listeners)
+- Listener lifecycle support via `lifecycle.enabled` and `lifecycle.types`
+- Sandbox test delivery endpoint (`POST /listeners/{id}/sandbox:send`)
+- Webhook signature verification (`X-Notamify-Signature`)
+- Typed webhook event models for `interpretation` and `lifecycle` payloads
+- Embedded receiver + cloudflared helper for local webhook testing
+- Strict receiver mode fails fast when webhook secret is missing
+
+## Install
+
+```bash
+pip install notamify-sdk
+```
+
+Or with `uv`:
+
+```bash
+uv add notamify-sdk
+```
+
+For contributors working from a source checkout:
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Environment variables (highest priority):
+
+- `NOTAMIFY_TOKEN`
+- `NOTAMIFY_API_BASE_URL`
+- `NOTAMIFY_WATCHER_BASE_URL`
+- `NOTAMIFY_WEBHOOK_SECRET`
+- `NOTAMIFY_CONFIG_FILE`
+
+Default config file: `~/.config/notamify/config.json`
+
+## Usage
+
+```python
+from notamify_sdk import NotamifyClient
+
+client = NotamifyClient(token="YOUR_TOKEN")
+
+# The API accepts at most 30 items per page.
+active_notams = list(client.notams.active({
+    "location": ["KJFK", "KLAX"],
+    "per_page": 30,
+}))
+print(len(active_notams))
+
+first_page = next(iter(client.notams.active({
+    "location": ["KJFK", "KLAX"],
+    "per_page": 30,
+}).pages))
+print(first_page.total_count)
+
+job = client.create_async_briefing({
+    "locations": [{
+        "location": "KJFK",
+        "type": "origin",
+        "starts_at": "2026-02-25T10:00:00Z",
+        "ends_at": "2026-02-25T12:00:00Z",
+    }],
+})
+print(job.uuid)
+
+# Watcher sandbox flow
+listener = client.create_listener(
+    "https://example.trycloudflare.com/webhooks/notamify",
+    mode="sandbox",
+    lifecycle={"enabled": False},
+)
+print(listener.webhook_secret)
+sandbox_result = client.send_sandbox_message(listener.id, "SANDBOX-NOTAM-1")
+print(sandbox_result.notam_id)
+```
+
+## Pagination
+
+The SDK exposes two NOTAM access styles:
+
+- `client.get_active_notams(...)`, `client.get_raw_notams(...)`, `client.get_nearby_notams(...)`, and `client.get_historical_notams(...)` return a single `NotamListResult` page.
+- `client.notams.active(...)`, `client.notams.raw(...)`, `client.notams.nearby(...)`, and `client.notams.historical(...)` return a pager that fetches all pages lazily as you iterate.
+
+Use the pager when you want all NOTAMs across pages:
+
+```python
+pager = client.notams.active(
+    {"location": ["KJFK", "KLAX"]},
+    per_page=30,
+)
+
+for notam in pager:
+    print(notam.id)
+```
+
+If you want everything in memory at once, materialize the pager with `list(...)`:
+
+```python
+all_notams = list(
+    client.notams.active(
+        {"location": ["KJFK", "KLAX"]},
+        per_page=30,
+    )
+)
+```
+
+If you need page metadata such as `page`, `per_page`, or `total_count`, iterate over `pager.pages`:
+
+```python
+pager = client.notams.active(
+    {"location": ["KJFK", "KLAX"]},
+    per_page=30,
+)
+
+for page in pager.pages:
+    print(page.page, page.total_count, len(page.notams))
+```
+
+The API allows at most `30` items per page. The SDK validates this with Pydantic and rejects larger `per_page` values.
+
+## Local Webhook Testing
+
+The example scripts live in the repository and source distribution under `examples/`.
+They are intended to be run from a source checkout or source distribution, not from an installed wheel alone.
+
+- Production: implement the webhook endpoint in your own application code.
+- Verify `X-Notamify-Signature` using `NOTAMIFY_WEBHOOK_SECRET`.
+- Production watcher deliveries include `kind`, `event_id`, and `notam`.
+- Lifecycle watcher deliveries also include `change.changed_notam_id` for the original NOTAM that was cancelled or replaced.
+- Local development: expose your local app endpoint with `cloudflared`, then set watcher `webhook_url` to that tunnel URL.
+- Sandbox test sends use the same webhook payload DTO as production sends, with mock NOTAM content.
+
+Prerequisite: `cloudflared` must be installed and available in `PATH`.
+
+```bash
+export NOTAMIFY_TOKEN="your_notamify_token"
+export LOCAL_APP_URL="http://127.0.0.1:8080/webhooks/notamify"
+uv run python ./examples/local_service_run.py
+```
+
+## Examples
+
+- `examples/service_receiver.py`: minimal production-style webhook receiver
+- `examples/local_service_run.py`: cloudflared tunnel + sandbox delivery flow
+- `examples/notams_fetch.py`: straightforward NOTAM query examples
+- `examples/README.md`: setup notes and sample payloads
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_*.py'
+```
+
+## License
+
+MIT

notamify_sdk-0.1.0/examples/README.md

@@ -0,0 +1,128 @@
+# Notamify Examples (Python)
+
+These examples cover watcher webhook integration and NOTAM data fetching.
+Run them from a source checkout or source distribution after installing dependencies with `uv sync`.
+
+## 1) Copy-paste receiver into your service
+
+Use this file as your base:
+
+- `examples/service_receiver.py`
+
+Run it locally:
+
+```bash
+export NOTAMIFY_WEBHOOK_SECRET="your_webhook_secret"
+export NOTAMIFY_WEBHOOK_PATH="/webhooks/notamify"
+uv run python ./examples/service_receiver.py
+```
+
+Replace `handle_notamify_event(event)` with your business logic.
+
+## 2) End-to-end local test against your service
+
+This script:
+
+- starts cloudflared tunnel to your local app origin
+- derives watcher `webhook_url` from tunnel host + your local path
+- creates/updates one listener in test mode (`mode=sandbox`)
+- calls `POST /listeners/{id}/sandbox:send` to trigger a webhook
+- retries transient DNS propagation errors
+
+Prerequisite: `cloudflared` must be installed and available in `PATH`.
+
+```bash
+export NOTAMIFY_TOKEN="your_notamify_token"
+export LOCAL_APP_URL="http://127.0.0.1:8080/webhooks/notamify"
+uv run python ./examples/local_service_run.py
+```
+
+Optional:
+
+- `NOTAMIFY_LISTENER_ID`
+- `NOTAMIFY_LISTENER_NAME` (default `notamify-sdk-sandbox-example`)
+
+Create a token in the [Notamify API Manager](https://notamify.com/api-manager).
+
+## 3) Fetch NOTAMs with the SDK pager
+
+This script keeps the NOTAM examples intentionally simple. It makes a few direct SDK calls with the NOTAM pager resource:
+
+- `client.notams.active(...)`
+- `client.notams.raw(...)`
+- `client.notams.nearby(...)`
+- `client.notams.historical(...)`
+
+It also shows how to access the first page metadata via `pager.pages`.
+
+Use `per_page` values up to `30`; larger values are rejected by the SDK query models.
+
+```bash
+export NOTAMIFY_TOKEN="your_notamify_token"
+uv run python ./examples/notams_fetch.py
+```
+
+Edit the ICAO codes, coordinates, or page sizes in `examples/notams_fetch.py` to match your own use case.
+
+## Webhook payload DTO
+
+Sandbox test sends and production sends use the same webhook payload DTO. Watcher can send standard `interpretation` messages and optional `lifecycle` messages for later NOTAMC/NOTAMR changes when the listener has `lifecycle.enabled = true`.
+
+```json
+{
+  "listener_id": "listener-123",
+  "kind": "interpretation",
+  "event_id": "event-123",
+  "notam": {
+    "id": "A1234/26",
+    "notam_number": "A1234/26",
+    "notam_type": "N",
+    "location": "EPWA",
+    "icao_code": "EPWA",
+    "qcode": "QMRLC",
+    "classification": "INTL",
+    "starts_at": "2026-02-25T12:00:00Z",
+    "ends_at": "2026-02-25T13:00:00Z",
+    "issued_at": "2026-02-25T11:55:00Z",
+    "is_estimated": false,
+    "is_permanent": false,
+    "message": "NOTAM text",
+    "icao_message": "NOTAM text",
+    "interpretation": {
+      "description": "Human summary",
+      "excerpt": "Short summary",
+      "category": "AERODROME",
+      "subcategory": "RUNWAY_OPERATIONS",
+      "map_elements": [],
+      "affected_elements": [],
+      "schedules": []
+    }
+  },
+  "context": {
+    "location": {
+      "ident": "EPWA",
+      "icao": "EPWA",
+      "name": "Warsaw Chopin Airport",
+      "iso_country": "PL",
+      "iso_country_name": "Poland",
+      "coordinates": {
+        "lat": 52.1657,
+        "lon": 20.9671
+      },
+      "fir_icaos": ["EPWW"]
+    }
+  },
+  "sent_at": "2026-02-25T13:09:51Z"
+}
+```
+
+Lifecycle payloads use the same top-level structure, but set `kind` to `"lifecycle"` and add:
+
+```json
+{
+  "change": {
+    "changed_notam_id": "old-notam-uuid",
+    "notam_type": "R"
+  }
+}
+```