dwy-webhooks 0.1.1__py3-none-any.whl

dwy_webhooks/__init__.py

@@ -0,0 +1,21 @@
+"""基于 EAPI 的 Webhook 集成；配置由项目注入，平台 SDK 按需加载。"""
+
+from .config import WebhookConfig
+from .errors import WebhookDeliveryError
+from .events import WebhookEvent
+from .fastapi import WebhookRuntime, WebhookSinks, install_webhooks
+from .validation import validate_discord_webhook_url
+
+__all__ = [
+    "DiscordWebhookSender", "WebhookConfig", "WebhookDeliveryError", "WebhookEvent",
+    "WebhookRuntime", "WebhookSinks", "install_webhooks", "validate_discord_webhook_url",
+]
+
+
+def __getattr__(name: str):
+    """核心导入不强制安装 Discord SDK；只有使用发送能力才加载该 extra。"""
+    if name == "DiscordWebhookSender":
+        from .discord import DiscordWebhookSender
+
+        return DiscordWebhookSender
+    raise AttributeError(name)

dwy_webhooks/config.py

@@ -0,0 +1,126 @@
+"""外部注入的配置契约；不读取环境变量、dotenv 或任何项目设置。"""
+
+import base64
+import binascii
+from itertools import combinations
+from typing import Annotated, Literal
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    SecretStr,
+    field_validator,
+    model_validator,
+)
+
+from .validation import paths_overlap, validate_discord_webhook_url
+
+
+def _destination(value):
+    """共享官方目标校验；空环境值关闭目标，错误不得回显凭据。"""
+    if value is None or value == "":
+        return None
+    raw = value.get_secret_value() if isinstance(value, SecretStr) else value
+    validate_discord_webhook_url(raw)
+    return value
+
+
+Destination = Annotated[SecretStr | None, BeforeValidator(_destination)]
+EventType = Annotated[str, Field(min_length=1, max_length=100, pattern=r"^[A-Za-z0-9_.-]+$")]
+AppKey = Annotated[str, Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$")]
+ASCAppID = Annotated[str, Field(min_length=1, max_length=20, pattern=r"^[0-9]+$")]
+LocalPath = Annotated[str, Field(max_length=256, pattern=r"^/(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+$")]
+ScopedPath = Annotated[str, Field(max_length=256, pattern=r"^/(?:[A-Za-z0-9_-]+/)+\{app_id\}$")]
+
+
+class WebhookSourceConfig(BaseModel):
+    """已实际重复的来源选项：可覆盖发送目标，并按事件类型筛选。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    discord_webhook_url: Destination = Field(default=None, max_length=2048, repr=False)
+    # None 使用提供方适配器自己的已知事件集，避免配置与事件格式维护两份列表。
+    events: frozenset[EventType] | None = Field(default=None, max_length=100)
+
+
+class ResendWebhookConfig(WebhookSourceConfig):
+    """Resend 原文签名配置，不需要发送邮件的 API Key。"""
+
+    secret: SecretStr = Field(min_length=1, max_length=512, repr=False)
+    name: str = Field(default="Resend", min_length=1, max_length=100)
+    scope: AppKey = "resend"
+    path: LocalPath = "/webhooks/resend"
+
+    @field_validator("secret")
+    @classmethod
+    def valid_secret(cls, value: SecretStr) -> SecretStr:
+        """验证 Svix 密钥编码，不接受格式错误后在请求阶段静默失败。"""
+        raw = value.get_secret_value()
+        try:
+            if not raw.startswith("whsec_") or len(base64.b64decode(raw[6:], validate=True)) < 16:
+                raise ValueError
+        except (ValueError, binascii.Error):
+            raise ValueError("Resend requires a valid signing secret") from None
+        return value
+
+
+class AppStoreConnectApp(BaseModel):
+    """每个 App 的显示名称与独立 HMAC 密钥。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    name: str = Field(min_length=1, max_length=128)
+    secret: SecretStr = Field(min_length=32, max_length=512, repr=False)
+
+
+class AppStoreConnectWebhookConfig(WebhookSourceConfig):
+    """ASC 审核/构建通知；App ID 与签名密钥固定由项目配置。"""
+
+    apps: dict[ASCAppID, AppStoreConnectApp] = Field(min_length=1, max_length=100)
+    path: ScopedPath = "/webhooks/app-store-connect/{app_id}"
+
+
+class AppleNotificationApp(BaseModel):
+    """Server Notifications V2 身份及证书；不需要 App Cloud 商品目录。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    name: str = Field(default="Apple", min_length=1, max_length=100)
+    bundle_id: str = Field(min_length=1, max_length=255)
+    environment: Literal["Production", "Sandbox"] = "Production"
+    app_apple_id: int | None = Field(default=None, ge=1)
+    root_certificates: tuple[bytes, ...] = Field(min_length=1, max_length=8, repr=False)
+    enable_online_checks: bool = True
+    verification_workers: int = Field(default=2, ge=1, le=8)
+
+    @model_validator(mode="after")
+    def production_identity(self):
+        """生产环境必须同时校验 Apple App ID；不能退回 Sandbox 验证。"""
+        if self.environment == "Production" and self.app_apple_id is None:
+            raise ValueError("Production Apple notifications require app_apple_id")
+        return self
+
+
+class AppleNotificationsConfig(WebhookSourceConfig):
+    """多个独立 App 的 Server Notifications 接入配置。"""
+
+    apps: dict[AppKey, AppleNotificationApp] = Field(min_length=1, max_length=100)
+    path: ScopedPath = "/webhooks/apple/{app_id}"
+
+
+class WebhookConfig(BaseModel):
+    """由项目 Settings 显式组合；未配置来源不注册路由，不读取部署环境。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    discord_webhook_url: Destination = Field(default=None, max_length=2048, repr=False)
+    resend: ResendWebhookConfig | None = None
+    app_store_connect: AppStoreConnectWebhookConfig | None = None
+    apple_notifications: AppleNotificationsConfig | None = None
+
+    @model_validator(mode="after")
+    def unique_paths(self):
+        """显式配置不同来源时，不能让相同路径静默遮蔽另一验签协议。"""
+        paths = [source.path for source in
+                 (self.resend, self.app_store_connect, self.apple_notifications) if source is not None]
+        if any(paths_overlap(left, right) for left, right in combinations(paths, 2)):
+            raise ValueError("Webhook source paths must not overlap")
+        return self

dwy_webhooks/delivery.py

@@ -0,0 +1,153 @@
+"""外部会话、表与发送器驱动的持久投递；模块不连接或初始化项目数据库。"""
+
+import asyncio
+import math
+import re
+import time
+from collections.abc import Awaitable, Callable
+from uuid import uuid4
+
+from dwyeapi.logger import get_logger
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy import JSON, BigInteger, Column, Integer, MetaData, String, Table, select, update
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+
+from .errors import WebhookDeliveryError
+from .events import WebhookEvent
+
+
+class DeliveryPolicy(BaseModel):
+    """调用方可显式注入投递预算，缺省与已有 ASC 消费者行为一致。"""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    max_attempts: int = Field(default=8, ge=1, le=100)
+    batch_size: int = Field(default=25, ge=1, le=500)
+    lease_seconds: int = Field(default=60, ge=1, le=3600)
+    poll_seconds: float = Field(default=2, gt=0, le=3600, allow_inf_nan=False)
+    retry_cap_seconds: int = Field(default=3600, ge=1, le=86400)
+    provider_retry_cap_seconds: int = Field(default=86400, ge=1, le=604800)
+
+
+def build_delivery_table(metadata: MetaData, name: str = "webhook_deliveries", *,
+                         scope_length: int = 128) -> Table:
+    """仅构造表定义；调用项目通过自己的 Alembic 迁移管理实际 schema。
+
+    app_id 是来源内的隔离 scope；沿用已有字段名以兼容 ASC 账本。
+    一个表归属一个来源，由调用方分别注入，不能把不同来源写进同一表。
+    """
+    if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]{0,62}", name) is None or not 1 <= scope_length <= 255:
+        raise ValueError("Invalid webhook delivery table definition")
+    return Table(
+        name, metadata,
+        Column("app_id", String(scope_length), primary_key=True),
+        Column("id", String(128), primary_key=True),
+        Column("event_type", String(128), nullable=False),
+        Column("payload", JSON, nullable=False),
+        Column("status", String(20), nullable=False),
+        Column("attempts", Integer, nullable=False, server_default="0"),
+        Column("next_attempt_at", BigInteger, nullable=False, server_default="0"),
+        Column("lease_until", BigInteger, nullable=False, server_default="0"),
+        Column("lease_token", String(36)),
+        Column("error_code", String(64)),
+        Column("message_id", String(128)),
+    )
+
+
+class SQLAlchemyDeliveryQueue:
+    """每个来源拥有独立账本；发送在事务外，完成更新必须持有本轮租约。"""
+
+    def __init__(self, sessions, table: Table, sender: Callable[[str], Awaitable[str]], *,
+                 source: str, policy: DeliveryPolicy | None = None,
+                 clock: Callable[[], float] = time.time):
+        """资源全部由调用方注入；消费者不创建、迁移或关闭任何项目资源。"""
+        if re.fullmatch(r"[a-z][a-z0-9_.-]{0,63}", source) is None:
+            raise ValueError("Invalid webhook source")
+        self.sessions, self.table, self.sender = sessions, table, sender
+        self.source, self.clock = source, clock
+        self.policy = policy if policy is not None else DeliveryPolicy()
+
+    async def __call__(self, event: WebhookEvent) -> bool:
+        """接收器可直接作为 sink 注入；错误来源必须在持久化前拒绝。"""
+        if event.source != self.source:
+            raise ValueError("Webhook source does not match the delivery queue")
+        return await self.enqueue(event.scope, event.event_id, event.event_type, event.content)
+
+    async def enqueue(self, app_id: str, event_id: str, event_type: str, content: str) -> bool:
+        """原子去重和入队；返回后接收端才能向提供方确认成功。"""
+        table = self.table
+        async with self.sessions.begin() as db:
+            dialect = db.get_bind().dialect.name
+            factory = {"sqlite": sqlite_insert, "postgresql": pg_insert}.get(dialect)
+            if factory is None:
+                raise ValueError("Webhook queue requires PostgreSQL or SQLite")
+            result = await db.execute(factory(table).values(
+                app_id=app_id, id=event_id, event_type=event_type,
+                payload={"content": content}, status="pending",
+            ).on_conflict_do_nothing(index_elements=["app_id", "id"]))
+            return bool(result.rowcount)
+
+    async def process_pending(self) -> int:
+        """有界条件领取；进程崩溃后由其他消费者接管过期租约。"""
+        table, sent = self.table, 0
+        for _ in range(self.policy.batch_size):
+            now, token = int(self.clock()), str(uuid4())
+            ready = (table.c.status.in_(("pending", "retry", "processing")),
+                     table.c.next_attempt_at <= now, table.c.lease_until <= now)
+            async with self.sessions.begin() as db:
+                row = (await db.execute(select(table).where(*ready).order_by(
+                    table.c.next_attempt_at, table.c.app_id, table.c.id
+                ).limit(1))).mappings().first()
+                if row is None:
+                    break
+                key = (table.c.app_id == row["app_id"], table.c.id == row["id"])
+                claimed = await db.execute(update(table).where(*key, *ready).values(
+                    status="processing", lease_token=token, lease_until=now + self.policy.lease_seconds))
+                if not claimed.rowcount:
+                    continue
+                row = dict(row)
+            values = await self._send(row)
+            async with self.sessions.begin() as db:
+                result = await db.execute(update(table).where(
+                    *key, table.c.lease_token == token
+                ).values(**values, lease_token=None, lease_until=0))
+                sent += int(bool(result.rowcount) and values["status"] == "sent")
+        return sent
+
+    async def _send(self, row) -> dict:
+        failure = None
+        try:
+            message_id = await self.sender(row["payload"]["content"])
+            if not isinstance(message_id, str) or not 1 <= len(message_id) <= 128:
+                raise WebhookDeliveryError("webhook_invalid_response")
+        except WebhookDeliveryError as error:
+            failure = error
+        except Exception:
+            # 第三方 sender 的异常也不能泄露原文，且必须受重试次数约束。
+            failure = WebhookDeliveryError("webhook_delivery_error")
+        if failure is not None:
+            # 不持久化用户自定义 sender 可能抛出的地址或响应正文。
+            code = (failure.code if isinstance(failure.code, str)
+                    and re.fullmatch(r"[a-z][a-z0-9_.-]{0,63}", failure.code) else "webhook_delivery_error")
+            delay = 0
+            if (not isinstance(failure.retry_after, bool) and isinstance(failure.retry_after, (int, float))
+                    and math.isfinite(failure.retry_after) and failure.retry_after >= 0):
+                delay = min(math.ceil(failure.retry_after), self.policy.provider_retry_cap_seconds)
+            attempts = row["attempts"] + 1
+            return dict(
+                status="dead" if failure.permanent or attempts >= self.policy.max_attempts else "retry",
+                attempts=attempts,
+                next_attempt_at=int(self.clock()) + max(
+                    delay, min(self.policy.retry_cap_seconds, 2 ** attempts)),
+                error_code=code,
+            )
+        return dict(status="sent", message_id=message_id, error_code=None)
+
+    async def run(self) -> None:
+        """由调用项目的 lifespan 启停；未知失败只记录固定错误码。"""
+        while True:
+            try:
+                await self.process_pending()
+            except Exception:
+                get_logger(__name__).error("Webhook processor failed code=WEBHOOK_PROCESSOR_FAILED")
+            await asyncio.sleep(self.policy.poll_seconds)

dwy_webhooks/discord.py

@@ -0,0 +1,100 @@
+"""Discord 单次传输；消息内容、验签和重试账本不属于传输层。"""
+
+import logging
+import re
+from contextlib import asynccontextmanager
+from math import isfinite
+
+import httpx
+from discord_webhook import AsyncDiscordWebhook
+
+from .errors import WebhookDeliveryError
+from .validation import validate_discord_webhook_url
+
+
+class _WebhookCredentialsFilter(logging.Filter):
+    """渲染后移除 token，正常 HTTP 请求日志继续保留。"""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """修改已渲染消息并清空 args，避免日志格式化再次插入原始 token。"""
+        message = record.getMessage()
+        redacted = re.sub(
+            r"(https://discord\.com/api/(?:v10/)?webhooks/[0-9]+/)[A-Za-z0-9_-]+",
+            r"\1[REDACTED]", message,
+        )
+        if redacted != message:
+            record.msg, record.args = redacted, ()
+        return True
+
+
+# 常驻安装，避免并发请求在临时添加/移除过滤器时出现脱敏空窗。
+logging.getLogger("httpx").addFilter(_WebhookCredentialsFilter())
+
+
+def discord_client() -> httpx.AsyncClient:
+    """每次请求使用有界客户端，取消和异常时由上下文负责关闭。"""
+    return httpx.AsyncClient(
+        timeout=10, follow_redirects=False, headers={"User-Agent": "dwy-webhooks/0.1.1"}
+    )
+
+
+class _DiscordWebhook(AsyncDiscordWebhook):
+    """复用成熟 SDK 的载荷和查询参数，只替换受控客户端。"""
+
+    @property
+    @asynccontextmanager
+    async def http_client(self):
+        """禁止跟随重定向，防止将凭据发送到另一地址。"""
+        async with discord_client() as client:
+            yield client
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    """Discord 延迟单位为秒；畸形值交给调用方的默认退避。"""
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    value = body.get("retry_after") if isinstance(body, dict) else None
+    if value is None:
+        value = response.headers.get("Retry-After")
+    if isinstance(value, bool):
+        return None
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    return seconds if isfinite(seconds) and seconds >= 0 else None
+
+
+class DiscordWebhookSender:
+    """只发送一次并返回消息编号；不休眠、重发或保存领域状态。"""
+
+    def __init__(self, webhook_url: str):
+        """公共包独立使用时也必须校验目标；异常不回显传入 URL。"""
+        self._webhook_url = validate_discord_webhook_url(webhook_url)
+
+    async def __call__(self, content: str, *, suppress_embeds: bool = False) -> str:
+        """wait 确认实际消息；预览选项只映射 Discord 的原生消息标志。"""
+        webhook = _DiscordWebhook(
+            url=self._webhook_url, content=content, allowed_mentions={"parse": []},
+            flags=4 if suppress_embeds else None, rate_limit_retry=False, timeout=10, wait=True,
+        )
+        try:
+            # execute() 会记录原始错误正文；只复用 SDK 的单次请求入口。
+            response = await webhook.api_post_request()
+        except httpx.HTTPError:
+            raise WebhookDeliveryError("discord_network_error") from None
+        if response.status_code == 429:
+            raise WebhookDeliveryError("discord_rate_limited", retry_after=_retry_after(response))
+        if not 200 <= response.status_code < 300:
+            raise WebhookDeliveryError("discord_http_error", permanent=300 <= response.status_code < 500)
+        try:
+            body = response.json()
+        except ValueError:
+            raise WebhookDeliveryError("discord_invalid_response") from None
+        message_id = body.get("id") if isinstance(body, dict) else None
+        if (not isinstance(message_id, str) or not message_id.isascii()
+                or not message_id.isdigit() or len(message_id) > 128):
+            raise WebhookDeliveryError("discord_invalid_response")
+        return message_id

dwy_webhooks/errors.py

@@ -0,0 +1,21 @@
+"""沿用 EAPI 异常基础，只传递安全错误码与调度建议。"""
+
+from dwyeapi.exceptions import AppError
+
+
+class WebhookDeliveryError(AppError):
+    """发送失败；是否重试及如何持久化由调用方决定。"""
+
+    def __init__(self, code: str, *, retry_after: float | None = None, permanent: bool = False):
+        """retry_after 为有限非负秒数；生产发送器只使用固定错误码。"""
+        self.code, self.retry_after, self.permanent = code, retry_after, permanent
+        super().__init__(code, code=code)
+
+
+class WebhookVerificationError(AppError):
+    """提供方验签失败的安全结果；原始 JWS 与 SDK 异常不得向外传播。"""
+
+    def __init__(self, code: str = "signature_invalid", *, status_code: int = 401):
+        """status_code 区分无效签名与可重试的验证服务暂时不可用。"""
+        self.code, self.status_code = code, status_code
+        super().__init__(code, code=code)

dwy_webhooks/events.py

@@ -0,0 +1,20 @@
+"""跨来源的已验证通知，不包含签名、凭据或原始邮件内容。"""
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class WebhookEvent:
+    """scope 隔离同一提供方的不同应用；data 仅携带适配器筛选后的元数据。"""
+
+    source: str
+    scope: str
+    event_id: str
+    event_type: str
+    content: str
+    data: Mapping[str, object] = field(default_factory=dict, repr=False)
+
+
+# True 表示本次接受，False 表示已接受的重复；异常必须阻止 HTTP 成功确认。
+EventSink = Callable[[WebhookEvent], Awaitable[bool]]

dwy_webhooks/fastapi.py

@@ -0,0 +1,117 @@
+"""FastAPI 一次注册入口；来源配置、去重与关闭生命周期都由模块装配。"""
+
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from dwyeapi.exceptions import register_exception_handlers
+from fastapi import APIRouter, FastAPI
+
+from .config import WebhookConfig, WebhookSourceConfig
+from .events import EventSink
+from .sinks import DiscordRelay, MemoryReceiptStore, ReceiptStore
+
+
+class _CloseableVerifier(Protocol):
+    """只约束安装器实际需要的关闭能力，不引入来源业务模型。"""
+
+    async def aclose(self) -> None:
+        """等待验证资源安全退出。"""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class WebhookSinks:
+    """有自己账本的项目可按来源替换接收行为；缺省使用 DiscordRelay。"""
+
+    resend: EventSink | None = None
+    app_store_connect: EventSink | None = None
+    apple_notifications: EventSink | None = None
+
+
+@dataclass(slots=True)
+class WebhookRuntime:
+    """属于当前 FastAPI 实例的集成资源，不包含宿主配置或数据库。"""
+
+    receipts: ReceiptStore
+    verifiers: list[_CloseableVerifier] = field(default_factory=list, repr=False)
+    closed: bool = False
+
+    async def aclose(self) -> None:
+        """幂等关闭全部验证器；即使某一关闭失败也继续释放其余资源。"""
+        if self.closed:
+            return
+        try:
+            async with AsyncExitStack() as stack:
+                for verifier in self.verifiers:
+                    stack.push_async_callback(verifier.aclose)
+        finally:
+            self.closed = True
+
+
+def _sink(source: WebhookSourceConfig, config: WebhookConfig,
+          override: EventSink | None, receipts: ReceiptStore) -> EventSink:
+    """自定义接收优先；自动转发必须显式配置可信 Discord 目标。"""
+    if override is not None:
+        return override
+    destination = source.discord_webhook_url or config.discord_webhook_url
+    if destination is None:
+        raise ValueError("Enabled webhook source requires a Discord target or a custom sink")
+    return DiscordRelay(destination.get_secret_value(), receipts)
+
+
+def install_webhooks(app: FastAPI, config: WebhookConfig, *,
+                     sinks: WebhookSinks | None = None,
+                     receipts: ReceiptStore | None = None) -> WebhookRuntime:
+    """注册全部已配置来源；复用原宿主 lifespan，公开 URL 可由独立配置选择。"""
+    if hasattr(app.state, "dwy_webhooks"):
+        raise ValueError("Webhooks already installed on this application")
+    selected = sinks if sinks is not None else WebhookSinks()
+    store = receipts if receipts is not None else MemoryReceiptStore()
+    runtime = WebhookRuntime(store)
+    router = APIRouter()
+    # 先验证默认接收器，避免配置错误后留下已注册的半套路由。
+    resend_sink = (_sink(config.resend, config, selected.resend, store)
+                   if config.resend is not None else None)
+    asc_sink = (_sink(config.app_store_connect, config, selected.app_store_connect, store)
+                if config.app_store_connect is not None else None)
+    apple_sink = (_sink(config.apple_notifications, config, selected.apple_notifications, store)
+                  if config.apple_notifications is not None else None)
+    if config.resend is not None:
+        from .providers.resend import create_resend_router
+
+        router.include_router(create_resend_router(config.resend, resend_sink))
+    if config.app_store_connect is not None:
+        from .providers.app_store_connect import create_asc_router
+
+        router.include_router(create_asc_router(config.app_store_connect, asc_sink))
+    if config.apple_notifications is not None:
+        from .providers.apple import AppleNotificationVerifier, create_apple_router
+
+        verifiers = {key: AppleNotificationVerifier(application)
+                     for key, application in config.apple_notifications.apps.items()}
+        runtime.verifiers.extend(verifiers.values())
+        router.include_router(create_apple_router(config.apple_notifications, apple_sink, verifiers))
+    previous_lifespan = app.router.lifespan_context
+
+    @asynccontextmanager
+    async def lifespan(application):
+        """原项目启动失败或关闭异常时，也释放当前集成自己的资源。"""
+        try:
+            async with previous_lifespan(application) as state:
+                yield state
+        finally:
+            await runtime.aclose()
+
+    app.include_router(router)
+    app.router.lifespan_context = lifespan
+    app.state.dwy_webhooks = runtime
+    return runtime
+
+
+def create_app(config: WebhookConfig) -> FastAPI:
+    """显式配置的独立 ASGI 应用；配置读取与密钥获取属于调用项目。"""
+    app = FastAPI(title="Webhooks", docs_url=None, redoc_url=None, openapi_url=None)
+    register_exception_handlers(app)
+    install_webhooks(app, config)
+    return app

dwy_webhooks/providers/__init__.py

@@ -0,0 +1,29 @@
+"""来源适配器共用的 HTTP 边界，不导入宿主、数据库或其他来源模块。"""
+
+from fastapi import HTTPException, Request
+
+from ..errors import WebhookDeliveryError
+from ..events import EventSink, WebhookEvent
+
+
+async def read_payload(request: Request, max_bytes: int = 65536) -> bytes:
+    """读取期间限制实际字节，不信任可省略或伪造的 Content-Length。"""
+    raw = bytearray()
+    async for chunk in request.stream():
+        raw.extend(chunk)
+        if len(raw) > max_bytes:
+            raise HTTPException(413, "Webhook payload is too large")
+    return bytes(raw)
+
+
+async def accept_event(sink: EventSink, event: WebhookEvent) -> dict[str, bool]:
+    """只有接收/转发成功才确认；失败不得写成成功去重或吞掉上游重试。"""
+    try:
+        accepted = await sink(event)
+    except WebhookDeliveryError as error:
+        message = ("Invalid notification acknowledgement" if error.code == "discord_invalid_response"
+                   else "Notification delivery failed")
+        raise HTTPException(502, message) from None
+    if not isinstance(accepted, bool):
+        raise RuntimeError("Webhook sink must return an acceptance boolean")
+    return {"received": True, "duplicate": not accepted}

dwy_webhooks/providers/app_store_connect.py

@@ -0,0 +1,139 @@
+"""App Store Connect 入站适配：按应用验原始字节 HMAC，不依赖宿主账本。"""
+
+import hashlib
+import hmac
+import json
+from datetime import datetime
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field, ValidationError
+
+from ..config import AppStoreConnectWebhookConfig
+from ..events import EventSink, WebhookEvent
+from . import accept_event, read_payload
+
+EVENTS = {
+    "appStoreVersionAppVersionStateUpdated": ("版本审核状态", "appStoreVersions"),
+    "buildUploadStateUpdated": ("构建上传状态", "buildUploads"),
+}
+STATES = {
+    "PREPARE_FOR_SUBMISSION": "准备提交", "READY_FOR_REVIEW": "准备送审",
+    "WAITING_FOR_REVIEW": "等待审核", "IN_REVIEW": "审核中",
+    "WAITING_FOR_EXPORT_COMPLIANCE": "等待出口合规处理", "PENDING_CONTRACT": "等待协议处理",
+    "REJECTED": "审核被拒", "METADATA_REJECTED": "元数据被拒",
+    "DEVELOPER_REJECTED": "开发者撤回", "INVALID_BINARY": "构建无效",
+    "PENDING_DEVELOPER_RELEASE": "审核通过，等待开发者发布",
+    "PENDING_APPLE_RELEASE": "等待 Apple 发布", "PROCESSING_FOR_APP_STORE": "正在处理上架",
+    "READY_FOR_SALE": "已上架", "READY_FOR_DISTRIBUTION": "可供分发",
+    "REMOVED_FROM_SALE": "已下架", "DEVELOPER_REMOVED_FROM_SALE": "开发者已下架",
+    "REPLACED_WITH_NEW_VERSION": "已被新版本替代", "ACCEPTED": "上传已接收",
+    "PROCESSING": "上传处理中", "COMPLETE": "上传处理完成", "FAILED": "上传处理失败",
+}
+
+
+class EventAttributes(BaseModel):
+    """两类状态通知字段不同；时间和原状态并非总是存在。"""
+
+    newValue: str | None = Field(default=None, min_length=1, max_length=128)
+    oldValue: str | None = Field(default=None, min_length=1, max_length=128)
+    newState: str | None = Field(default=None, min_length=1, max_length=128)
+    timestamp: datetime | None = None
+
+
+class Resource(BaseModel):
+    """外部 JSON:API 资源只取有界标识，不访问传入的 URL。"""
+
+    type: str = Field(min_length=1, max_length=128)
+    id: str = Field(min_length=1, max_length=128)
+
+
+class Instance(BaseModel):
+    """事件关联的版本或构建上传资源。"""
+
+    data: Resource
+
+
+class Relationships(BaseModel):
+    """仅选择版本/构建状态事件后才要求 instance 关联。"""
+
+    instance: Instance
+
+
+class StatusEvent(Resource):
+    """验证已选择的状态事件，不要求未选通知携带同一结构。"""
+
+    version: int = Field(ge=1, le=100)
+    attributes: EventAttributes
+    relationships: Relationships
+
+
+class Envelope(BaseModel):
+    """先验证公共事件头，再判断是否为 ping 或已选择的状态类型。"""
+
+    data: Resource
+
+
+def message(app_id: str, name: str, event: StatusEvent) -> str:
+    """保留 Apple 原始状态；未知枚举可读，不猜测拒审原因或版本号。"""
+    attrs = event.attributes
+    state = attrs.newValue if event.type == "appStoreVersionAppVersionStateUpdated" else attrs.newState
+    if state is None or event.relationships.instance.data.type != EVENTS[event.type][1]:
+        raise ValueError("invalid status event")
+    lines = [f"App Store Connect · {EVENTS[event.type][0]}", f"应用：{name}",
+             f"状态：{STATES.get(state, state)} ({state})"]
+    if attrs.oldValue:
+        lines.append(f"原状态：{STATES.get(attrs.oldValue, attrs.oldValue)} ({attrs.oldValue})")
+    if attrs.timestamp:
+        lines.append(f"事件时间：{attrs.timestamp.isoformat()}")
+    lines.extend([f"记录编号：{event.relationships.instance.data.id}", f"通知编号：{event.id}",
+                  f"后台：https://appstoreconnect.apple.com/apps/{app_id}/distribution"])
+    return "\n".join(lines)
+
+
+def create_asc_router(config: AppStoreConnectWebhookConfig, sink: EventSink) -> APIRouter:
+    """按配置挂载应用独立密钥；接收语义由可替换的 sink 决定。"""
+    router = APIRouter()
+
+    @router.post(config.path, include_in_schema=False)
+    async def receive(app_id: str, request: Request):
+        """签名覆盖原始字节；只在下游确认接收后向 Apple 返回成功。"""
+        application = config.apps.get(app_id)
+        if application is None:
+            raise HTTPException(404, "Webhook is not configured")
+        raw = await read_payload(request)
+        digest = hmac.new(application.secret.get_secret_value().encode(), raw, hashlib.sha256).hexdigest()
+        supplied = request.headers.get("x-apple-signature", "")
+        if not supplied.isascii() or not hmac.compare_digest(supplied, "hmacsha256=" + digest):
+            raise HTTPException(401, "Invalid webhook signature")
+        try:
+            envelope = Envelope.model_validate_json(raw)
+            event_type, event_id = envelope.data.type, envelope.data.id
+            selected = config.events if config.events is not None else {*EVENTS, "webhookPingCreated"}
+            if event_type not in selected:
+                return {"received": True, "ignored": True}
+            if event_type == "webhookPingCreated":
+                content = "\n".join([
+                    "App Store Connect · 官方连通测试", f"应用：{application.name}",
+                    "说明：验证 Apple → Cloud → Discord；不代表审核状态变化",
+                    f"通知编号：{event_id}",
+                    f"后台：https://appstoreconnect.apple.com/apps/{app_id}/distribution",
+                ])
+                data = {"app_id": app_id}
+            elif event_type in EVENTS:
+                event = StatusEvent.model_validate(json.loads(raw)["data"])
+                content = message(app_id, application.name, event)
+                state = (event.attributes.newValue if event_type == "appStoreVersionAppVersionStateUpdated"
+                         else event.attributes.newState)
+                data = {"app_id": app_id, "instance_id": event.relationships.instance.data.id, "state": state}
+            else:
+                # 已配置但尚无适配器的类型仍明确忽略，不伪造可处理事件。
+                return {"received": True, "ignored": True}
+        except (ValidationError, ValueError, UnicodeError):
+            raise HTTPException(400, "Invalid webhook event") from None
+        prepared = WebhookEvent(
+            source="app_store_connect", scope=app_id, event_id=event_id, event_type=event_type,
+            content=content, data=data,
+        )
+        return await accept_event(sink, prepared)
+
+    return router

dwy_webhooks/providers/apple.py

@@ -0,0 +1,231 @@
+"""可移植的 App Store Server Notifications V2 接收与官方验签边界。"""
+
+import asyncio
+import json
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, HTTPException, Request
+
+from ..config import AppleNotificationApp, AppleNotificationsConfig
+from ..errors import WebhookVerificationError
+from ..events import EventSink, WebhookEvent
+from . import accept_event, read_payload
+
+
+def _text(value, *, maximum: int = 255) -> str:
+    """约束已验签字段的结构，不把 SDK 的 None 或任意对象直接转成文本。"""
+    value = getattr(value, "value", value)
+    if not isinstance(value, str) or not 1 <= len(value) <= maximum:
+        raise ValueError("invalid notification field")
+    return value
+
+
+def _date(milliseconds) -> datetime:
+    """Apple 时间戳为 UTC 毫秒，拒绝布尔值、缺失及溢出。"""
+    if isinstance(milliseconds, bool) or not isinstance(milliseconds, (int, float)):
+        raise ValueError("invalid notification date")
+    return datetime.fromtimestamp(milliseconds / 1000, UTC)
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedAppleNotification:
+    """仅包含已验签的安全元数据，不保存 JWS、账户 token 或任意外部正文。"""
+
+    notification_id: str
+    bundle_id: str
+    environment: str
+    notification_type: str
+    signed_at: datetime
+    subtype: str | None = None
+    product_id: str | None = None
+    transaction_id: str | None = None
+
+    def public_data(self) -> dict[str, str | None]:
+        """向项目回调提供稳定字段；这些数据不会授予任何购买权益。"""
+        return {
+            "notification_id": self.notification_id, "bundle_id": self.bundle_id,
+            "environment": self.environment, "notification_type": self.notification_type,
+            "subtype": self.subtype, "signed_at": self.signed_at.isoformat(),
+            "product_id": self.product_id, "transaction_id": self.transaction_id,
+        }
+
+
+class AppleNotificationVerifier:
+    """每个配置应用独占官方 verifier；签名线程与在途任务均有上限。"""
+
+    def __init__(self, config: AppleNotificationApp):
+        """生产必须声明 App Apple ID；根证书字节由调用项目显式注入。"""
+        if config.environment == "Production" and config.app_apple_id is None:
+            raise ValueError("Production Apple notifications require app_apple_id")
+        self.config = config
+        self._verifier = None
+        self._closed = False
+        self._executor = ThreadPoolExecutor(
+            max_workers=config.verification_workers, thread_name_prefix="webhook-apple-verify"
+        )
+        self._semaphore = asyncio.Semaphore(config.verification_workers)
+        self._pending: set[asyncio.Future] = set()
+
+    def _sdk(self):
+        """延迟构造 SDK，缺失能力和证书错误仅返回固定的不可用分类。"""
+        if self._closed:
+            raise WebhookVerificationError("apple_verifier_closed", status_code=503)
+        if self._verifier is None:
+            try:
+                from appstoreserverlibrary.models.Environment import Environment
+                from appstoreserverlibrary.signed_data_verifier import SignedDataVerifier
+
+                roots = list(self.config.root_certificates)
+                if not roots:
+                    raise ValueError("missing roots")
+                self._verifier = SignedDataVerifier(
+                    roots, self.config.enable_online_checks, Environment(self.config.environment),
+                    self.config.bundle_id, self.config.app_apple_id,
+                )
+            except (ImportError, OSError, ValueError):
+                raise WebhookVerificationError("apple_verifier_unavailable", status_code=503) from None
+        return self._verifier
+
+    async def _verify(self, method: str, signed: str):
+        """取消等待不提前释放在途预算，防止慢在线检查堆积无限线程池任务。"""
+        if not isinstance(signed, str) or not 1 <= len(signed) <= 131072:
+            raise WebhookVerificationError("apple_signature_invalid")
+        verifier = self._sdk()
+        await self._semaphore.acquire()
+        if self._closed:
+            self._semaphore.release()
+            raise WebhookVerificationError("apple_verifier_closed", status_code=503)
+        future = asyncio.get_running_loop().run_in_executor(self._executor, getattr(verifier, method), signed)
+        self._pending.add(future)
+
+        def finished(done):
+            """实际签名工作完成才释放预算，并消费被取消调用者留下的异常。"""
+            self._pending.discard(done)
+            self._semaphore.release()
+            if not done.cancelled():
+                done.exception()
+
+        future.add_done_callback(finished)
+        try:
+            return await asyncio.shield(future)
+        except Exception as error:
+            from appstoreserverlibrary.signed_data_verifier import VerificationException, VerificationStatus
+
+            if (isinstance(error, VerificationException)
+                    and error.status == VerificationStatus.RETRYABLE_VERIFICATION_FAILURE):
+                raise WebhookVerificationError("apple_verification_unavailable", status_code=503) from None
+            raise WebhookVerificationError("apple_signature_invalid") from None
+
+    async def verify(self, signed_payload: str) -> VerifiedAppleNotification:
+        """外层通知和每个嵌套 JWS 分别验签，再检查交易关系与元数据结构。"""
+        notice = await self._verify("verify_and_decode_notification", signed_payload)
+        try:
+            data = notice.data
+            target = data or notice.summary or getattr(notice, "appData", None)
+            external = getattr(notice, "externalPurchaseToken", None)
+            if target is None:
+                target = external
+            if target is None:
+                raise ValueError("missing notification identity")
+            bundle_id = _text(target.bundleId)
+            if target is external:
+                environment = ("Sandbox" if (external.externalPurchaseId or "").startswith("SANDBOX")
+                               else "Production")
+            else:
+                environment = _text(target.environment, maximum=32)
+            if bundle_id != self.config.bundle_id or environment != self.config.environment:
+                raise ValueError("notification identity mismatch")
+            if self.config.environment == "Production" and target.appAppleId != self.config.app_apple_id:
+                raise ValueError("notification application mismatch")
+            transaction = None
+            if data and data.signedTransactionInfo:
+                transaction = await self._verify(
+                    "verify_and_decode_signed_transaction", data.signedTransactionInfo
+                )
+                if (_text(transaction.bundleId) != bundle_id
+                        or _text(transaction.environment, maximum=32) != environment):
+                    raise ValueError("transaction identity mismatch")
+            if data and data.signedRenewalInfo:
+                renewal = await self._verify("verify_and_decode_renewal_info", data.signedRenewalInfo)
+                if transaction:
+                    original = _text(transaction.originalTransactionId, maximum=128)
+                    if _text(renewal.originalTransactionId, maximum=128) != original:
+                        raise ValueError("transaction renewal mismatch")
+            return VerifiedAppleNotification(
+                notification_id=_text(notice.notificationUUID, maximum=128), bundle_id=bundle_id,
+                environment=environment, notification_type=_text(notice.notificationType, maximum=100),
+                signed_at=_date(notice.signedDate),
+                subtype=_text(notice.subtype, maximum=100) if notice.subtype is not None else None,
+                product_id=_text(transaction.productId) if transaction is not None else None,
+                transaction_id=(_text(transaction.transactionId, maximum=128)
+                                if transaction is not None else None),
+            )
+        except (AttributeError, TypeError, ValueError, OverflowError, OSError):
+            raise WebhookVerificationError("apple_notification_invalid") from None
+
+    async def aclose(self) -> None:
+        """关闭后拒绝新工作，等待有界签名任务退出并回收线程资源。"""
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            if self._pending:
+                await asyncio.gather(*tuple(self._pending), return_exceptions=True)
+        finally:
+            self._executor.shutdown(wait=False, cancel_futures=True)
+
+
+def _content(name: str, notice: VerifiedAppleNotification) -> str:
+    """仅描述签名事实，不把取消续订、共享授权或测试通知误称为收入。"""
+    event_type = notice.notification_type
+    if notice.subtype is not None:
+        event_type += f" / {notice.subtype}"
+    lines = [
+        f"{name} · Apple 内购状态通知", f"环境：{notice.environment}", f"事件：{event_type}",
+        f"通知编号：{notice.notification_id}",
+        f"Apple 签名时间：{notice.signed_at.isoformat(timespec='seconds')}",
+    ]
+    if notice.product_id is not None:
+        lines.append(f"商品：{notice.product_id}")
+    if notice.transaction_id is not None:
+        lines.append(f"交易编号：{notice.transaction_id}")
+    return "\n".join(lines)
+
+
+def create_apple_router(
+    config: AppleNotificationsConfig, sink: EventSink, verifiers: dict[str, AppleNotificationVerifier],
+) -> APIRouter:
+    """安装来源路由；verifier 由注册器持有并在宿主关闭时回收。"""
+    router = APIRouter()
+
+    @router.post(config.path, include_in_schema=False)
+    async def receive(app_id: str, request: Request):
+        """先定位固定配置，再限流读取和完整验签，最后投递已选事件。"""
+        application = config.apps.get(app_id)
+        verifier = verifiers.get(app_id)
+        if application is None or verifier is None:
+            raise HTTPException(404, "Webhook is not configured")
+        raw = await read_payload(request, max_bytes=262144)
+        try:
+            body = json.loads(raw)
+            signed = body.get("signedPayload") if isinstance(body, dict) else None
+            if not isinstance(signed, str) or not 1 <= len(signed) <= 131072:
+                raise ValueError("invalid signed payload")
+        except (ValueError, UnicodeError):
+            raise HTTPException(400, "Invalid Apple notification") from None
+        try:
+            notice = await verifier.verify(signed)
+        except WebhookVerificationError as error:
+            raise HTTPException(error.status_code, "Apple notification verification failed") from None
+        if config.events is not None and notice.notification_type not in config.events:
+            return {"received": True, "ignored": True}
+        event = WebhookEvent(
+            source="apple_notifications", scope=app_id, event_id=notice.notification_id,
+            event_type=notice.notification_type, content=_content(application.name, notice),
+            data=notice.public_data(),
+        )
+        return await accept_event(sink, event)
+
+    return router

dwy_webhooks/providers/resend.py

@@ -0,0 +1,68 @@
+"""Resend 入站适配：官方 SDK 验签后只交付事件元数据，不读取邮件正文。"""
+
+import resend
+from fastapi import APIRouter, HTTPException, Request
+
+from ..config import ResendWebhookConfig
+from ..events import EventSink, WebhookEvent
+from . import accept_event, read_payload
+
+# 未显式选择的事件不进入发送链；新事件文案仅在此来源文件扩展。
+EVENT_LABELS = {
+    "email.received": "收到新邮件",
+    "email.sent": "邮件已发送",
+    "email.delivered": "邮件已送达",
+    "email.failed": "邮件发送失败",
+    "email.bounced": "邮件退信",
+    "email.complained": "邮件被标记为垃圾邮件",
+    "email.delivery_delayed": "邮件投递延迟",
+    "email.suppressed": "邮件被抑制发送",
+    "email.opened": "邮件被打开",
+    "email.clicked": "邮件链接被点击",
+}
+
+
+def create_resend_router(config: ResendWebhookConfig, sink: EventSink) -> APIRouter:
+    """独立项目只提供来源配置和接收接口，去重或持久化属于 sink。"""
+    router = APIRouter()
+
+    @router.post(config.path, include_in_schema=False)
+    async def receive(request: Request):
+        """先限制并验证原始载荷，再解析类型，最后确认下游接收结果。"""
+        raw = await read_payload(request)
+        event_id = request.headers.get("svix-id", "")
+        if not event_id or len(event_id) > 256:
+            raise HTTPException(401, "Invalid webhook signature")
+        try:
+            event = resend.Webhooks.verify({
+                "payload": raw.decode("utf-8"),
+                "headers": {
+                    "id": event_id,
+                    "timestamp": request.headers.get("svix-timestamp", ""),
+                    "signature": request.headers.get("svix-signature", ""),
+                },
+                "webhook_secret": config.secret.get_secret_value(),
+            })
+        except (ValueError, UnicodeError):
+            raise HTTPException(401, "Invalid webhook signature") from None
+        if not isinstance(event, dict) or not isinstance(event.get("type"), str):
+            raise HTTPException(400, "Invalid webhook event")
+        event_type = event["type"]
+        selected = config.events if config.events is not None else EVENT_LABELS
+        if event_type not in selected:
+            return {"received": True, "ignored": True}
+        data = event.get("data")
+        if not isinstance(data, dict) or not isinstance(data.get("email_id"), str):
+            raise HTTPException(400, "Invalid email event")
+        email_id = data["email_id"][:128]
+        content = "\n".join([
+            f"{config.name} · {EVENT_LABELS.get(event_type, event_type)}",
+            f"事件：{event_type}", f"邮件编号：{email_id}", f"通知编号：{event_id}",
+        ])
+        prepared = WebhookEvent(
+            source="resend", scope=config.scope, event_id=event_id, event_type=event_type,
+            content=content, data={"email_id": email_id},
+        )
+        return await accept_event(sink, prepared)
+
+    return router

dwy_webhooks/sinks.py

@@ -0,0 +1,68 @@
+"""缺省同步转发及有界去重；需要持久接收的项目可以注入自己的 sink。"""
+
+import asyncio
+from collections import OrderedDict
+from typing import Protocol
+
+from .events import WebhookEvent
+
+EventKey = tuple[str, str, str]
+
+
+class ReceiptStore(Protocol):
+    """可替换的已送达记录；不能把尚未送达的消息提前记作成功。"""
+
+    async def contains(self, key: EventKey) -> bool:
+        """查询来源、应用、通知编号组成的完整隔离键。"""
+        ...
+
+    async def add(self, key: EventKey) -> None:
+        """仅在目标确认发送成功后记录。"""
+        ...
+
+
+class MemoryReceiptStore:
+    """实例内有界 LRU；重启后上游重投可能再次发送，不承诺持久去重。"""
+
+    def __init__(self, capacity: int = 4096):
+        """限制内存增长；共享多进程去重需由调用方提供原子持久接收入口。"""
+        if not 1 <= capacity <= 100000:
+            raise ValueError("Receipt capacity must be between 1 and 100000")
+        self.capacity = capacity
+        self._items: OrderedDict[EventKey, None] = OrderedDict()
+
+    async def contains(self, key: EventKey) -> bool:
+        """不执行阻塞 I/O；由 relay 的锁保护检查到提交之间的竞态。"""
+        if key not in self._items:
+            return False
+        self._items.move_to_end(key)
+        return True
+
+    async def add(self, key: EventKey) -> None:
+        """淘汰最旧的成功记录，不保存签名、消息正文或密钥。"""
+        self._items[key] = None
+        self._items.move_to_end(key)
+        if len(self._items) > self.capacity:
+            self._items.popitem(last=False)
+
+
+class DiscordRelay:
+    """发送成功才接受事件；网络故障由接收端返回失败供提供方重试。"""
+
+    def __init__(self, webhook_url: str, receipts: ReceiptStore | None = None):
+        """锁和去重状态属于当前集成，不存在跨项目的模块全局状态。"""
+        from .discord import DiscordWebhookSender
+
+        self.sender = DiscordWebhookSender(webhook_url)
+        self.receipts = receipts if receipts is not None else MemoryReceiptStore()
+        self._lock = asyncio.Lock()
+
+    async def __call__(self, event: WebhookEvent) -> bool:
+        """所有提供方按完整身份去重；失败和取消都不会提交已送达记录。"""
+        key = (event.source, event.scope, event.event_id)
+        async with self._lock:
+            if await self.receipts.contains(key):
+                return False
+            await self.sender(event.content, suppress_embeds=True)
+            await self.receipts.add(key)
+            return True

dwy_webhooks/validation.py

@@ -0,0 +1,20 @@
+"""不依赖平台 SDK 的目标校验，用于配置和可选发送器。"""
+
+import re
+
+
+def paths_overlap(left: str, right: str) -> bool:
+    """已校验路径仅有末尾 app_id 参数，静态与模板同形时必须拒绝。"""
+    first, second = left.split("/"), right.split("/")
+    return len(first) == len(second) and all(
+        a == b or a == "{app_id}" or b == "{app_id}" for a, b in zip(first, second, strict=True)
+    )
+
+
+def validate_discord_webhook_url(value: str) -> str:
+    """只接受官方 HTTPS 地址，不回显无效输入中的凭据。"""
+    if not isinstance(value, str) or re.fullmatch(
+        r"https://discord\.com/api/(?:v10/)?webhooks/[0-9]+/[A-Za-z0-9_-]+", value
+    ) is None:
+        raise ValueError("discord_webhook_url requires an official Discord HTTPS webhook URL")
+    return value

dwy_webhooks-0.1.1.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: dwy-webhooks
+Version: 0.1.1
+Summary: 独立于业务来源的 Webhook 发送、安全边界与失败语义
+Requires-Python: <3.13,>=3.11
+Requires-Dist: dwyeapi==0.12.0
+Provides-Extra: apple
+Requires-Dist: app-store-server-library[async]==3.1.2; extra == 'apple'
+Provides-Extra: dev
+Requires-Dist: aiosqlite==0.22.1; extra == 'dev'
+Requires-Dist: httpx==0.28.1; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: ruff==0.15.12; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: discord-webhook[async]==1.4.1; extra == 'discord'
+Requires-Dist: httpx==0.28.1; extra == 'discord'
+Provides-Extra: resend
+Requires-Dist: resend==2.49.1; extra == 'resend'
+Description-Content-Type: text/markdown
+
+# dwy-webhooks
+
+基于 EAPI 的通用 Webhook 模块。接收 Resend、App Store Connect、Apple Server Notifications V2，并按项目配置转发到 Discord 或外部注入的业务接收函数。
+
+## 安装与依赖
+
+核心依赖固定兼容版本 `dwyeapi`；平台 SDK 按需选择 `dwy-webhooks[discord,resend,apple]`。ASC 使用标准库 HMAC；只有 Apple Server Notifications 需要 Apple SDK。源码由 dwy-shared 维护，项目安装独立 wheel，不引用共享仓库的绝对源码路径。发布配置不表示已经发布。
+
+## 配置与接入
+
+库不读取环境变量、`.env`、项目设置或证书文件。`WebhookConfig` 是纯 Pydantic 模型；项目可组合进自己的 EAPI Settings。密钥由项目取得后传入，Apple 根证书传入字节。
+
+```python
+from dwy_webhooks import WebhookConfig, install_webhooks
+from dwy_webhooks.config import ResendWebhookConfig
+
+# app 与 project_settings 都属于调用项目；库不再回读环境。
+config = WebhookConfig(
+    discord_webhook_url=project_settings.discord_webhook_url,
+    resend=ResendWebhookConfig(
+        secret=project_settings.resend_webhook_secret,
+        name="My Project", events=frozenset({"email.received", "email.failed"}),
+    ),
+)
+runtime = install_webhooks(app, config)
+```
+
+Resend 使用 Webhook 签名密钥，不使用发送邮件的 API Key。未配置来源不注册路由；各来源可独立覆盖 Discord 目标、事件集合和接收路径。
+
+- `AppStoreConnectWebhookConfig(apps={app_id: AppStoreConnectApp(name=..., secret=...)})` 配置审核、构建及 ping 通知。
+- `AppleNotificationsConfig(apps={key: AppleNotificationApp(name=..., bundle_id=..., environment="Production", app_apple_id=..., root_certificates=(certificate_bytes, ...))})` 配置 Server Notifications V2。
+- 将前两者放入 `WebhookConfig.app_store_connect`、`.apple_notifications` 后，一次注册即可接入。
+- 默认路径：`/webhooks/resend`、`/webhooks/app-store-connect/{app_id}`、`/webhooks/apple/{app_id}`；完整公开 URL 由项目域名及反向代理决定。
+
+## 资源与接收语义
+
+- 默认 `DiscordRelay` 在发送成功后确认，实例内保留最多 4096 条成功记录。失败返回非 2xx 供提供方重试。重启可能再次发送，这不是持久或恰好一次投递保证。
+- 项目可注入 `ReceiptStore`，或通过 `WebhookSinks` 按来源注入接收函数。函数接收已验证的 `WebhookEvent`，返回 True 表示接受、False 表示重复；异常不能被确认成功。
+- `SQLAlchemyDeliveryQueue` 提供持久队列，sessions、table、sender、source 和可选策略由外部注入。使用 EAPI 创建的会话，不创建、迁移或关闭项目数据库。一个表固定一个来源，防止跨来源编号碰撞。
+- `build_delivery_table` 注册到项目 metadata，由项目自己的 Alembic 管理 schema。库不在注册路由时自动建表。
+- `install_webhooks` 保留宿主生命周期，只关闭自己拥有的验证器；`create_app(config)` 可建立独立 ASGI 应用，配置仍然必填。普通错误复用 EAPI，第三方成功 ACK 保持提供方协议。
+
+```python
+from dwy_webhooks import WebhookSinks, install_webhooks
+
+# persist_verified_event 是项目自己的持久入口，或已注入资源的队列实例。
+install_webhooks(app, config, sinks=WebhookSinks(app_store_connect=persist_verified_event))
+```
+
+Apple 商品目录、账户绑定和权益发放保留在业务项目。通用模块只验证通知并提供安全事件元数据，不把测试通知或续订设置变更报告为收入。
+
+## 安全和扩展
+
+来源分别验签，并在读取原始字节时限制体积。Apple 外层、交易及续订 JWS 分别走官方 SDK，生产强制 App Apple ID。Discord 固定官方 HTTPS 地址，拒绝重定向和 mentions，等待有效消息编号；错误不记录 token 或原始响应正文。
+
+新增来源增加 provider，新增目标增加 transport；共用事件、sink 和 EAPI 资源，避免平台大分支。注册入口不覆盖项目已有的全局异常或缓存配置。
+
+`examples/new_project/app.py` 是不依赖 App Cloud 的接入示例。隔离 wheel 验收要求 `app_cloud`、`apple_iap`、`cloud_kernel`、旧 `cloud_webhooks` 和产品包缺席，公共配置、注册和三类来源仍能通过测试。

dwy_webhooks-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+dwy_webhooks/__init__.py,sha256=ic2O8u9FilNpo32XCKEvldlsDJMQXIEhfa-szfiEyM0,795
+dwy_webhooks/config.py,sha256=gIV5R1ktPwX_KVe4aEGAQhDWjmKkpWyxCdpajWq4pNs,5343
+dwy_webhooks/delivery.py,sha256=e6YsJm2weCN5cAcE1ox8U2aJIcegj_xeopgw3rcyq7U,7994
+dwy_webhooks/discord.py,sha256=KsPrb_5oVYV5Cy_z98kOlv72SCiDmHgsqI4UjmNdz60,4053
+dwy_webhooks/errors.py,sha256=fPP2USVxIdmeDAYptMIu8xPXN71jtbhwzoPbu6hS5rU,963
+dwy_webhooks/events.py,sha256=bznvA4fwbMP3GUjIkMcDaxBDybks67m2AEnrAwQA3Yg,662
+dwy_webhooks/fastapi.py,sha256=jP3vk9BuutUbwa0QJW2ig-i-LPmJLiKSjVmc5qNvdgc,4997
+dwy_webhooks/sinks.py,sha256=axhtFHMymo5fn5_wNg-AgyEEK82zULHdx8gEXM_vPjY,2669
+dwy_webhooks/validation.py,sha256=9bXQ1EmnLbdqI--_72WhHuDHz3caJitDMTzVnfV1mi8,832
+dwy_webhooks/providers/__init__.py,sha256=KaV4w7dP6iQBVJTqnqNJPBacfEOuwI9GNZaaYa7rYZk,1267
+dwy_webhooks/providers/app_store_connect.py,sha256=hMJtiSyN-juq2lyz86-i7jB-KhM3NLIThhHIc9qc55A,6546
+dwy_webhooks/providers/apple.py,sha256=sFa0UdtbKnaHXNG2-lw24uOFtoYfAVugw67wjhGcNAg,11401
+dwy_webhooks/providers/resend.py,sha256=2Vx4QQYaIZ_XrnfFlZAuefCAIhToHQDSH6Ku_W3UBTg,3057
+dwy_webhooks-0.1.1.dist-info/METADATA,sha256=Re-pU0GBzM2Ns-GWRMUBVbkVM4Ql65xFuzfOd6iSKGE,5138
+dwy_webhooks-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dwy_webhooks-0.1.1.dist-info/RECORD,,

dwy_webhooks-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any