# retoor <retoor@molodetz.nl>

from .._shared import endpoint, field

GROUP = {
        "slug": "push",
        "title": "Web Push",
        "intro": """
# Web Push

Push notifications are delivered by one or more providers. `webpush` is the default and
implements the Web Push protocol: fetch the public VAPID key, then register a
`PushSubscription` obtained from the browser's `PushManager`. `apns` delivers to an Apple
Push Notification service device token and is only offered when an administrator has
configured it.

`GET /push.json` lists the providers that currently accept registrations. When `apns` is
active it includes `environment` (`production` or `sandbox`) so a native client can match
its build. A registration body without a `provider` field is a `webpush` registration, so
existing clients need no change. An APNs body may include a stable `client_id` so a later
token rotation updates the same device instead of inserting another row.

There is no server-side unsubscribe endpoint: unsubscription is handled entirely in the
browser by calling `PushManager.unsubscribe()` on the subscription. The server stops delivering
to a subscription once its push endpoint reports it as gone. These mirror the in-app
[Notifications](/docs/notifications.html) feed.

Every endpoint follows the shared [Conventions & Errors](/docs/conventions.html) (auth, content
negotiation, pagination, status codes); see [Authentication](/docs/authentication.html) for the
four ways to sign requests.
""",
        "endpoints": [
            endpoint(
                id="push-key",
                method="GET",
                path="/push.json",
                title="Get the public key",
                summary="Return the VAPID public key and the providers that accept registrations.",
                auth="public",
                sample_response={
                    "publicKey": "BASE64_VAPID_KEY",
                    "providers": {
                        "webpush": {"publicKey": "BASE64_VAPID_KEY"},
                        "apns": {"environment": "production"},
                    },
                },
            ),
            endpoint(
                id="push-register",
                method="POST",
                path="/push.json",
                title="Register a subscription",
                summary="Register a push subscription. Sends a welcome notification.",
                auth="user",
                encoding="json",
                interactive=False,
                params=[
                    field(
                        "provider",
                        "json",
                        "string",
                        False,
                        "webpush",
                        "Provider to register with. Omit for webpush.",
                    ),
                    field(
                        "endpoint",
                        "json",
                        "string",
                        False,
                        "https://fcm.googleapis.com/...",
                        "Subscription endpoint URL. Required for webpush.",
                    ),
                    field(
                        "keys",
                        "json",
                        "string",
                        False,
                        '{"p256dh":"...","auth":"..."}',
                        "Subscription keys object. Required for webpush.",
                    ),
                    field(
                        "token",
                        "json",
                        "string",
                        False,
                        "a1b2c3...",
                        "Hexadecimal device token. Required for apns. Spaces and angle brackets are stripped.",
                    ),
                    field(
                        "client_id",
                        "json",
                        "string",
                        False,
                        "vendor-uuid",
                        "Stable per-device id for apns. When present, a new token updates this device instead of inserting a row.",
                    ),
                ],
                notes=[
                    'A webpush body is JSON: `{"endpoint": "...", "keys": {"p256dh": "...", "auth": "..."}}`.',
                    'An APNs body is JSON: `{"provider": "apns", "token": "...", "client_id": "..."}`. `client_id` is optional; token-only bodies keep working and revive a previously dead token.',
                    "A provider that is unknown, disabled or unconfigured returns 400.",
                    "A newly created or revived registration is probed immediately. The response then includes `delivered` and, on failure, `error` with the provider reason. `registered` stays true so existing clients keep working.",
                ],
                sample_response={"registered": True, "delivered": True},
            ),
        ],
}
