notifyfork 0.1.2__tar.gz

notifyfork-0.1.2/.env.example

@@ -0,0 +1,46 @@
+# Environment variables read by NotifyFork's providers and webhooks.
+# Wire these into your own project's env/settings however you normally do —
+# NotifyFork doesn't ship a settings.py of its own.
+#
+# Only set the ones for the channels you're actually using; providers with
+# missing credentials are skipped at startup (see container/providers.py).
+
+# Twilio (SMS + WhatsApp)
+TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxx
+TWILIO_AUTH_TOKEN=your_auth_token
+TWILIO_FROM_NUMBER=+15551234567
+TWILIO_WHATSAPP_FROM_NUMBER=+15551234567
+
+# SendGrid
+SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxx
+SENDGRID_FROM_EMAIL=you@yourdomain.com
+SENDGRID_FROM_NAME=Your App
+
+# Resend
+RESEND_API_KEY=re_xxxxxxxxxxxxxxxx
+RESEND_FROM_EMAIL=you@yourdomain.com
+RESEND_FROM_NAME=Your App
+
+# SMTP (fallback email provider)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=465
+SMTP_USERNAME=you@gmail.com
+SMTP_PASSWORD=your_app_password
+SMTP_FROM_EMAIL=you@gmail.com
+
+# Firebase (push)
+FIREBASE_CREDENTIALS_PATH=credentials/firebase.json
+
+# Slack
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+
+# Webhook signature validation — set these on your project's settings.py,
+# read from wherever you like (TWILIO_AUTH_TOKEN above already covers Twilio).
+SENDGRID_WEBHOOK_PUBLIC_KEY=your_pub_key   # from SendGrid Event Webhook settings
+RESEND_WEBHOOK_SECRET=whsec_your_signing_secret   # from Resend Dashboard → Webhooks
+
+# Fallback order when more than one provider supports the same channel
+# (e.g. SendGrid + SMTP for email) — comma-separated provider names, tried
+# in order until one succeeds. Optional; defaults to DEFAULT_PROVIDER_ORDER
+# in container/providers.py if unset.
+NOTIFYFORK_PROVIDER_ORDER=sendgrid_email,resend_email,smtp_email

notifyfork-0.1.2/.github/workflows/auto-tag.yml

@@ -0,0 +1,51 @@
+name: Auto Tag
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  actions: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Read version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Version: $VERSION"
+
+      - name: Check if tag already exists
+        run: |
+          TAG="v${{ steps.version.outputs.version }}"
+          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" > /dev/null 2>&1; then
+            echo "::error::Tag $TAG already exists on origin. Bump the version in pyproject.toml before merging to main."
+            exit 1
+          fi
+          echo "Tag $TAG does not exist yet — OK to create."
+
+      - name: Create and push tag
+        run: |
+          TAG="v${{ steps.version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+
+      - name: Trigger publish workflow
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="v${{ steps.version.outputs.version }}"
+          # A tag pushed with GITHUB_TOKEN does NOT fire publish.yml's
+          # "on: push: tags" trigger (GitHub blocks GITHUB_TOKEN-authored
+          # events from cascading, to avoid workflow loops). workflow_dispatch
+          # is explicitly exempted from that rule, so we call it directly.
+          gh workflow run publish.yml --ref "$TAG"

notifyfork-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Fetch main
+        run: git fetch origin main:refs/remotes/origin/main
+
+      - name: Compare version against main
+        run: |
+          PR_VERSION=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          MAIN_VERSION=$(git show origin/main:pyproject.toml | grep -m1 '^version = ' | sed -E 's/version = "(.*)"/\1/')
+
+          echo "PR version:   $PR_VERSION"
+          echo "main version: $MAIN_VERSION"
+
+          if [ "$PR_VERSION" = "$MAIN_VERSION" ]; then
+            echo "::error::Version in pyproject.toml ($PR_VERSION) is the same as main. Bump it before merging."
+            exit 1
+          fi
+
+          HIGHEST=$(printf '%s\n%s\n' "$PR_VERSION" "$MAIN_VERSION" | sort -V | tail -n1)
+
+          if [ "$HIGHEST" != "$PR_VERSION" ]; then
+            echo "::error::Version in pyproject.toml ($PR_VERSION) is lower than main ($MAIN_VERSION). Bump it before merging."
+            exit 1
+          fi
+
+          echo "Version bump OK: $MAIN_VERSION -> $PR_VERSION"
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest

notifyfork-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  # auto-tag.yml pushes the tag using GITHUB_TOKEN, which GitHub excludes
+  # from triggering the "push: tags" event above (anti-loop protection).
+  # workflow_dispatch is exempt from that rule, so auto-tag.yml calls this
+  # explicitly (`gh workflow run publish.yml --ref vX.Y.Z`) after tagging.
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

notifyfork-0.1.2/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+.env
+credentials/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+PUBLISH.md

notifyfork-0.1.2/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to NotifyFork will be documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+### Added
+- `@notifyfork.provider` decorator to register a custom provider from outside the lib, no `NotificationProvider` subclassing required (duck-typed, same as everything else in the container)
+- `notifyfork.send()`, replacing `send_event()`. You pass `channel`, `template_id` and `notification_type` straight through instead of registering an event type first
+- `examples/custom_provider/register_xpto_provider.py` showing the provider decorator end to end
+
+### Changed
+- `examples/email/send_sendgrid_external.py` now actually hits the `order_confirmed_sg` template it documents. Under the old event routing it was silently sharing `order.confirmed`'s rule and sending through `order_confirmed` instead, so the SendGrid Dynamic Template path in that example never really ran
+- `channel` and `notification_type` are plain strings now, not the closed `NotificationChannel` / `NotificationType` enums, all the way through `SendNotificationDTO`, the `Notification` entity and the repository. A provider registered for a channel NotifyFork doesn't ship out of the box (Telegram, say) now works end to end through `notifyfork.send(channel="telegram", ...)` — previously pydantic rejected it before the provider was ever consulted. The enums are still there and still used by the built-in providers, they're just no longer enforced on the way in
+
+### Removed
+- `event_router.py`, `EventType` and `EVENT_ROUTING_TABLE`. That layer only translated an `event_type` string into `channel` + `template_id` before queueing, and the queue already accepted those fields directly. Every caller already knows the channel and template it wants, so there was nothing left for the router to decide
+- `send_event()`, replaced by `send()`
+
+## [0.1.0] - 2024-06-01
+
+### Added
+- Provider-agnostic notification gateway with event-driven routing
+- Channels: SMS (Twilio), Email (SMTP + SendGrid), WhatsApp (Twilio), Push (Firebase), Slack
+- LOCAL and EXTERNAL template modes with `VariableMapping` for provider-specific variable translation
+- Celery async dispatch with `acks_late`, exponential backoff, and periodic retry sweep
+- Django ORM repositories with full async support (`aupdate_or_create`, `aget`)
+- Dependency container that only registers providers with credentials configured
+- Django migrations with seed data for default templates
+- Full unit test suite with pytest + conftest shared fixtures
+- Runnable examples for every channel
+- Bilingual README (English + Portuguese)

notifyfork-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to NotifyFork
+
+First off, thank you for taking the time to contribute! 🎉
+
+## Ways to contribute
+
+- 🐛 **Report a bug**: open an [issue](https://github.com/marioasaraujo/notifyfork/issues) with steps to reproduce
+- 💡 **Suggest a feature**: open an issue with the `enhancement` label
+- 📖 **Improve documentation**: typos, clarity, translations
+- 🔌 **Add a new provider**: see guide below
+- ✅ **Fix a bug**: check open issues labeled `good first issue`
+
+## Development setup
+
+```bash
+git clone https://github.com/marioasaraujo/notifyfork
+cd notifyfork
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Running tests
+
+```bash
+pytest tests/unit -v --cov=notifyfork --cov-report=term-missing
+```
+
+Coverage must stay above **80%**. PRs that drop coverage will not be merged.
+
+## Adding a new provider
+
+1. Create `notifyfork/core/infrastructure/providers/your_provider.py`
+2. Extend `NotificationProvider`, implementing `name`, `supported_channels`, `send_with_template`
+3. Register in `notifyfork/core/infrastructure/container/providers.py`
+4. Add tests in `tests/unit/providers/test_your_provider.py`
+5. Add a runnable example in `examples/your_channel/`
+6. Update the channel table in `README.md`
+
+## Adding a new kind of notification
+
+There's no event catalog. Just add the template via a new migration in
+`notifyfork/core/infrastructure/migrations/`, then call `notifyfork.send(...)`
+with that `template_id` and whatever `channel` it belongs to.
+
+## Pull Request checklist
+
+- [ ] Tests pass (`pytest tests/unit`)
+- [ ] Coverage ≥ 80%
+- [ ] New provider has at least one example in `examples/`
+- [ ] README updated if a new channel was added
+- [ ] `CHANGELOG.md` updated
+
+## Code style
+
+```bash
+ruff check notifyfork tests   # lint
+ruff format notifyfork tests  # format
+mypy notifyfork                # type check
+```
+
+## Questions?
+
+Open an issue or reach out directly, see the [README](README.md#contact) for contact info.

notifyfork-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mario Araujo
+
+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.