agentcore-notifier 0.1.0__py3-none-any.whl

agentcore_notifier/__init__.py

@@ -0,0 +1,3 @@
+"""Agentcore Notifier: webhook, email, and related notification management."""
+
+__version__ = "0.1.0"

agentcore_notifier/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters for agentcore_notifier."""

agentcore_notifier/adapters/django/__init__.py

@@ -0,0 +1 @@
+"""Django adapter for agentcore_notifier."""

agentcore_notifier/adapters/django/admin.py

@@ -0,0 +1,47 @@
+"""Admin for agentcore_notifier Django adapter."""
+from django.contrib import admin
+from django.utils.translation import gettext_lazy as _
+
+from agentcore_notifier.adapters.django.models import (
+    NotificationChannel,
+    NotificationRecord,
+    NotifierConfig,
+)
+
+
+@admin.register(NotificationRecord)
+class NotificationRecordAdmin(admin.ModelAdmin):
+    list_display = [
+        "id",
+        "provider_type",
+        "source_app",
+        "source_type",
+        "status",
+        "created_at",
+        "sent_at",
+    ]
+    list_filter = ["provider_type", "status", "source_app", "created_at"]
+    search_fields = ["source_app", "source_type", "source_id"]
+    readonly_fields = ["created_at", "sent_at"]
+    date_hierarchy = "created_at"
+    ordering = ["-created_at"]
+
+
+@admin.register(NotifierConfig)
+class NotifierConfigAdmin(admin.ModelAdmin):
+    list_display = ["scope", "user", "key", "updated_at"]
+    list_filter = ["scope", "key"]
+    search_fields = ["key"]
+    raw_id_fields = ["user"]
+    ordering = ["scope", "key"]
+
+
+@admin.register(NotificationChannel)
+class NotificationChannelAdmin(admin.ModelAdmin):
+    list_display = [
+        "id", "channel_type", "name", "is_active", "is_default",
+        "ordering", "created_at",
+    ]
+    list_filter = ["channel_type", "is_active", "is_default"]
+    search_fields = ["name"]
+    ordering = ["ordering", "created_at"]

agentcore_notifier/adapters/django/apps.py

@@ -0,0 +1,14 @@
+"""Django app config for agentcore_notifier."""
+from django.apps import AppConfig
+
+
+class AgentcoreNotifierDjangoConfig(AppConfig):
+    """App config for agentcore_notifier Django adapter."""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "agentcore_notifier.adapters.django"
+    label = "agentcore_notifier"
+    verbose_name = "Agentcore Notifier"
+
+    def ready(self):
+        pass

agentcore_notifier/adapters/django/cleanup.py

@@ -0,0 +1,80 @@
+"""
+Cleanup of old notification records.
+Uses conf when arguments are omitted. Call directly or via Celery task.
+"""
+import logging
+from datetime import timedelta
+from typing import Any, Dict, Optional
+
+from django.utils import timezone
+
+from agentcore_notifier.adapters.django.conf import (
+    get_cleanup_only_completed,
+    get_retention_days,
+)
+from agentcore_notifier.adapters.django.models import NotificationRecord
+from agentcore_notifier.constants import Status
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BATCH_SIZE = 5000
+
+
+def cleanup_old_notification_records(
+    retention_days: Optional[int] = None,
+    only_completed: Optional[bool] = None,
+    batch_size: Optional[int] = None,
+) -> Dict[str, Any]:
+    """
+    Delete notification records older than retention_days.
+    only_completed=True: only delete status in (success, failed).
+    """
+    if retention_days is None:
+        retention_days = get_retention_days()
+    if only_completed is None:
+        only_completed = get_cleanup_only_completed()
+
+    if retention_days <= 0:
+        logger.warning(
+            f"cleanup_old_notification_records: retention_days="
+            f"{retention_days} <= 0, skipping"
+        )
+        return {
+            "deleted_count": 0,
+            "cutoff": timezone.now(),
+            "retention_days": retention_days,
+            "only_completed": only_completed,
+            "skipped": True,
+            "reason": "invalid_retention_days",
+        }
+
+    cutoff = timezone.now() - timedelta(days=retention_days)
+    base_qs = NotificationRecord.objects.filter(created_at__lt=cutoff)
+    if only_completed:
+        base_qs = base_qs.filter(status__in=(Status.SUCCESS, Status.FAILED))
+
+    # Delete in one go or in batches
+    if batch_size is None or batch_size <= 0:
+        deleted_count, _ = base_qs.delete()
+        total_deleted = deleted_count
+    else:
+        total_deleted = 0
+        while True:
+            batch = list(base_qs.values_list("pk", flat=True)[:batch_size])
+            if not batch:
+                break
+            batch_deleted, _ = (
+                NotificationRecord.objects.filter(pk__in=batch).delete()
+            )
+            total_deleted += batch_deleted
+
+    logger.info(
+        f"cleanup_old_notification_records: deleted={total_deleted} "
+        f"retention_days={retention_days} only_completed={only_completed}"
+    )
+    return {
+        "deleted_count": total_deleted,
+        "cutoff": cutoff,
+        "retention_days": retention_days,
+        "only_completed": only_completed,
+    }

agentcore_notifier/adapters/django/conf.py

@@ -0,0 +1,164 @@
+"""
+Global config for agentcore_notifier (cleanup, merge). Not user-specific.
+Uses lazy imports of notification_config to avoid circular import.
+"""
+try:
+    from celery.schedules import crontab
+except ImportError:
+    crontab = None
+
+from django.conf import settings
+
+DEFAULT_RETENTION_DAYS = 180
+DEFAULT_CLEANUP_ONLY_COMPLETED = True
+DEFAULT_CLEANUP_ENABLED = True
+DEFAULT_CLEANUP_CRONTAB = "0 2 * * *"
+
+
+def _get_global_config():
+    # NOTE(Ray): Lazy import to avoid circular import.
+    from agentcore_notifier.adapters.django.services import notification_config
+
+    raw = notification_config.get_config("global")
+    return raw if isinstance(raw, dict) else {}
+
+
+def get_retention_days():
+    """
+    Retention days for cleanup: NotifierConfig key=global first, else settings.
+    """
+    g = _get_global_config()
+    v = g.get("retention_days")
+    if isinstance(v, int) and v > 0:
+        return v
+    return getattr(
+        settings,
+        "AGENTCORE_NOTIFIER_RETENTION_DAYS",
+        DEFAULT_RETENTION_DAYS,
+    )
+
+
+def get_cleanup_only_completed():
+    """Return whether cleanup deletes only completed records (default True)."""
+    return getattr(
+        settings,
+        "AGENTCORE_NOTIFIER_CLEANUP_ONLY_COMPLETED",
+        DEFAULT_CLEANUP_ONLY_COMPLETED,
+    )
+
+
+def get_cleanup_enabled():
+    """Return whether cleanup beat task is enabled (default True)."""
+    g = _get_global_config()
+    if "cleanup_enabled" in g:
+        return bool(g["cleanup_enabled"])
+    return getattr(
+        settings, "AGENTCORE_NOTIFIER_CLEANUP_ENABLED", DEFAULT_CLEANUP_ENABLED
+    )
+
+
+def get_cleanup_crontab():
+    """Return 5-field cron expression for cleanup (default daily 2:00)."""
+    g = _get_global_config()
+    v = g.get("cleanup_crontab")
+    if isinstance(v, str) and v.strip():
+        return v.strip()
+    return getattr(
+        settings, "AGENTCORE_NOTIFIER_CLEANUP_CRONTAB", DEFAULT_CLEANUP_CRONTAB
+    )
+
+
+def _crontab_from_expression(expr):
+    """Parse 5-field cron into Celery crontab. On parse error returns None."""
+    if not crontab or not expr:
+        return None
+    parts = str(expr).strip().split()
+    if len(parts) != 5:
+        return None
+    try:
+        return crontab(
+            minute=parts[0],
+            hour=parts[1],
+            day_of_month=parts[2],
+            month_of_year=parts[3],
+            day_of_week=parts[4],
+        )
+    except (TypeError, ValueError):
+        return None
+
+
+def get_cleanup_beat_schedule(interval_hours=None):
+    """Beat schedule for cleanup. Uses get_cleanup_crontab() or interval."""
+    task_name = (
+        "agentcore_notifier.adapters.django.tasks.cleanup."
+        "cleanup_old_notification_records_task"
+    )
+    if interval_hours is not None:
+        schedule = interval_hours * 3600.0
+    else:
+        schedule = _crontab_from_expression(get_cleanup_crontab())
+        if schedule is None:
+            schedule = 24 * 3600.0
+    return {
+        "agentcore-notifier-cleanup-old-records": {
+            "task": task_name,
+            "schedule": schedule,
+            "options": {},
+        }
+    }
+
+
+def get_cleanup_beat_schedule_init(interval_hours=None):
+    """
+    Build cleanup beat schedule from Django settings only (no DB).
+    For use in AppConfig.ready() to avoid database-during-init warning.
+    Runtime DB config is still applied when the cleanup task runs.
+    """
+    task_name = (
+        "agentcore_notifier.adapters.django.tasks.cleanup."
+        "cleanup_old_notification_records_task"
+    )
+    if interval_hours is not None:
+        schedule = interval_hours * 3600.0
+    else:
+        crontab_str = getattr(
+            settings,
+            "AGENTCORE_NOTIFIER_CLEANUP_CRONTAB",
+            DEFAULT_CLEANUP_CRONTAB,
+        )
+        schedule = _crontab_from_expression(crontab_str)
+        if schedule is None:
+            schedule = 24 * 3600.0
+    return {
+        "agentcore-notifier-cleanup-old-records": {
+            "task": task_name,
+            "schedule": schedule,
+            "options": {},
+        }
+    }
+
+
+def get_merge_enabled(provider_type: str) -> bool:
+    """Return whether merge is enabled for this provider (default False)."""
+    # NOTE(Ray): Lazy import to avoid circular import.
+    from agentcore_notifier.adapters.django.services import notification_config
+
+    key = f"channel_{provider_type}"
+    raw = notification_config.get_config(key)
+    if isinstance(raw, dict) and "merge_enabled" in raw:
+        return bool(raw["merge_enabled"])
+    return False
+
+
+def get_merge_window_minutes(provider_type: str):
+    """Return merge window in minutes for this provider, or None (disabled)."""
+    # NOTE(Ray): Lazy import to avoid circular import.
+    from agentcore_notifier.adapters.django.services import notification_config
+
+    key = f"channel_{provider_type}"
+    raw = notification_config.get_config(key)
+    if isinstance(raw, dict):
+        v = raw.get("merge_window_minutes")
+        if isinstance(v, int) and v > 0:
+            return v
+    return None

agentcore_notifier/adapters/django/locale/zh_Hans/LC_MESSAGES/django.po

@@ -0,0 +1,74 @@
+# agentcore-notifier Chinese (Simplified) translations
+msgid ""
+msgstr ""
+"Project-Id-Version: agentcore-notifier\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-25 00:00+0800\n"
+"PO-Revision-Date: 2026-06-25 00:00+0800\n"
+"Language-Team: zh_Hans\n"
+"Language: zh_Hans\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+
+# views/channels.py — webhook validation
+msgid "Webhook URL not configured"
+msgstr "Webhook 地址未配置，请先填写 Webhook URL"
+
+msgid "[%s] Channel validation test"
+msgstr "[%s] 渠道连通性测试"
+
+msgid "Send failed"
+msgstr "发送失败，请检查 Webhook 地址及网络连通性"
+
+msgid "Validation failed"
+msgstr "验证失败"
+
+# views/channels.py — email validation
+msgid "SMTP host not configured"
+msgstr "SMTP 服务器地址未配置"
+
+msgid "From address required to send test"
+msgstr "发送测试邮件需要先配置发件人地址（From）"
+
+msgid "(connection only)"
+msgstr "（仅测试连接，未发送邮件）"
+
+msgid "[%s] Email validation test"
+msgstr "[%s] 邮件渠道连通性测试"
+
+msgid "[%s] Email channel validation test"
+msgstr "这是来自 [%s] 的邮件渠道连通性测试，收到此邮件说明 SMTP 配置正确。"
+
+msgid ""
+"Server cannot reach SMTP host (no route). "
+"Check deployment: firewall/security group outbound, "
+"or container network. Original: "
+msgstr ""
+"服务器无法访问 SMTP 主机（网络不可达）。"
+"请检查：防火墙/安全组出站规则、容器网络配置是否正确。原始错误："
+
+msgid ""
+"SMTP connection timed out. Check server network and "
+"firewall/proxy. Original: "
+msgstr ""
+"SMTP 连接超时，请检查服务器网络、防火墙或代理配置。原始错误："
+
+# services/webhook_service.py
+msgid "Invalid response format from webhook. Expected JSON but got: {}"
+msgstr "Webhook 返回格式异常，期望 JSON 格式，实际收到：{}"
+
+msgid "Webhook request failed with HTTP status {}. Response: {}"
+msgstr "Webhook 请求失败，HTTP 状态码 {}，响应内容：{}"
+
+msgid ""
+"Webhook validation failed: {}. Please check if the webhook URL is "
+"correct, or verify security settings (e.g., IP whitelist, API key)."
+msgstr ""
+"Webhook 验证失败：{}。请确认 Webhook 地址是否正确，"
+"并检查安全配置（如 IP 白名单、访问密钥）。"
+
+# services/webhook/feishu.py & wechat.py
+msgid "Webhook error code {}"
+msgstr "Webhook 业务错误，错误码 {}"

agentcore_notifier/adapters/django/migrations/0001_initial.py

@@ -0,0 +1,206 @@
+# Initial migration for agentcore_notifier Django adapter.
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="NotificationRecord",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("source_app", models.CharField(max_length=100)),
+                ("source_type", models.CharField(blank=True, max_length=100)),
+                ("source_id", models.CharField(blank=True, max_length=100)),
+                (
+                    "source_metadata",
+                    models.JSONField(blank=True, default=dict),
+                ),
+                (
+                    "channel",
+                    models.CharField(default="webhook", max_length=50),
+                ),
+                (
+                    "provider_type",
+                    models.CharField(
+                        choices=[
+                            ("feishu", "Feishu"),
+                            ("wecom", "WeCom"),
+                            ("wechat", "WeChat Work"),
+                            ("email", "Email"),
+                        ],
+                        db_index=True,
+                        max_length=20,
+                    ),
+                ),
+                (
+                    "target",
+                    models.JSONField(blank=True, default=dict),
+                ),
+                ("payload", models.JSONField()),
+                (
+                    "template_key",
+                    models.CharField(blank=True, max_length=100),
+                ),
+                (
+                    "locale",
+                    models.CharField(blank=True, max_length=20),
+                ),
+                (
+                    "content_metadata",
+                    models.JSONField(blank=True, default=dict),
+                ),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("success", "Success"),
+                            ("failed", "Failed"),
+                            ("merged", "Merged"),
+                            ("silenced", "Silenced"),
+                        ],
+                        db_index=True,
+                        default="pending",
+                        max_length=20,
+                    ),
+                ),
+                ("response", models.JSONField(blank=True, null=True)),
+                ("error_message", models.TextField(blank=True)),
+                ("sent_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "provider_message_id",
+                    models.CharField(blank=True, max_length=255),
+                ),
+                (
+                    "metadata",
+                    models.JSONField(blank=True, default=dict),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True, db_index=True)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="+",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "notifier_notification_record",
+                "ordering": ["-created_at"],
+                "verbose_name": "Notification Record",
+                "verbose_name_plural": "Notification Records",
+            },
+        ),
+        migrations.CreateModel(
+            name="NotifierConfig",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "scope",
+                    models.CharField(
+                        choices=[("global", "Global"), ("user", "User")],
+                        db_index=True,
+                        default="global",
+                        max_length=20,
+                    ),
+                ),
+                (
+                    "key",
+                    models.CharField(db_index=True, max_length=128),
+                ),
+                (
+                    "value",
+                    models.JSONField(
+                        default=dict,
+                        help_text="Config payload (JSON).",
+                    ),
+                ),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        blank=True,
+                        help_text="Null for global scope; set for user-level override.",
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="+",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "agentcore_notifier_config",
+                "verbose_name": "Notifier Config",
+                "verbose_name_plural": "Notifier Configs",
+            },
+        ),
+        migrations.AddIndex(
+            model_name="notificationrecord",
+            index=models.Index(
+                fields=[
+                    "provider_type",
+                    "source_app",
+                    "source_type",
+                    "source_id",
+                ],
+                name="notifier_no_provider_source_4a7c80_idx",
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="notificationrecord",
+            index=models.Index(
+                fields=["status", "created_at"],
+                name="notifier_no_status_created_2b0f3a_idx",
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="notificationrecord",
+            index=models.Index(
+                fields=["created_at"],
+                name="notifier_no_created_at_1f8d9e_idx",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="notifierconfig",
+            constraint=models.UniqueConstraint(
+                fields=("scope", "user", "key"),
+                name="agentcore_notifier_config_scope_user_key_uniq",
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="notifierconfig",
+            index=models.Index(
+                fields=["scope", "key"],
+                name="agentcore_notifier_config_scope_key_idx",
+            ),
+        ),
+    ]

agentcore_notifier/adapters/django/migrations/0002_webhookchannel.py

@@ -0,0 +1,53 @@
+# NotificationChannel model: single table for webhook/email/sms channels.
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("agentcore_notifier", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="NotificationChannel",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                (
+                    "channel_type",
+                    models.CharField(
+                        choices=[("webhook", "Webhook"), ("email", "Email"), ("sms", "SMS")],
+                        db_index=True,
+                        max_length=20,
+                    ),
+                ),
+                ("name", models.CharField(blank=True, max_length=255)),
+                ("is_active", models.BooleanField(default=True)),
+                (
+                    "is_default",
+                    models.BooleanField(
+                        default=False,
+                        help_text="If True, this channel is used for sending when no channel is specified.",
+                    ),
+                ),
+                ("ordering", models.PositiveIntegerField(default=0)),
+                (
+                    "config",
+                    models.JSONField(
+                        blank=True,
+                        default=dict,
+                        help_text="Type-specific config, e.g. webhook: provider_type, url; email: smtp_host, port; sms: provider, api_key.",
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                "db_table": "notifier_channel",
+                "ordering": ["ordering", "created_at"],
+                "verbose_name": "Notification Channel",
+                "verbose_name_plural": "Notification Channels",
+            },
+        ),
+    ]

agentcore_notifier/adapters/django/migrations/0003_notificationrecord_channel_id.py

@@ -0,0 +1,26 @@
+# Add channel_id to NotificationRecord for per-channel merge scope.
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("agentcore_notifier", "0002_webhookchannel"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="notificationrecord",
+            name="channel_link",
+            field=models.ForeignKey(
+                blank=True,
+                db_column="channel_id",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="notification_records",
+                to="NotificationChannel",
+            ),
+        ),
+    ]