retoor
cae139ead9
DevPlace CI / test (push) Failing after 28m20s
Also streamline the top navigation: drop the Tools dropdown, make Quizzes and Battles icon-only entries, and remove the Workspace, Containers and Editor entry points from the project detail page.
160 lines
7.0 KiB
Python
160 lines
7.0 KiB
Python
# 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.
|
|
|
|
`DELETE /push.json` removes a single registration by the same identity used to create it
|
|
(`endpoint` for webpush, `token` or `client_id` for apns). The server also 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},
|
|
),
|
|
endpoint(
|
|
id="push-unregister",
|
|
method="DELETE",
|
|
path="/push.json",
|
|
title="Unregister a subscription",
|
|
summary="Remove one push registration by its identity.",
|
|
auth="user",
|
|
encoding="json",
|
|
interactive=False,
|
|
params=[
|
|
field(
|
|
"provider",
|
|
"json",
|
|
"string",
|
|
False,
|
|
"webpush",
|
|
"Provider the registration belongs to. Omit for webpush.",
|
|
),
|
|
field(
|
|
"endpoint",
|
|
"json",
|
|
"string",
|
|
False,
|
|
"https://fcm.googleapis.com/...",
|
|
"Subscription endpoint URL. Identifies a webpush registration.",
|
|
),
|
|
field(
|
|
"token",
|
|
"json",
|
|
"string",
|
|
False,
|
|
"a1b2c3...",
|
|
"Hexadecimal device token. Identifies an apns registration.",
|
|
),
|
|
field(
|
|
"client_id",
|
|
"json",
|
|
"string",
|
|
False,
|
|
"vendor-uuid",
|
|
"Stable per-device id. Identifies an apns registration when set.",
|
|
),
|
|
],
|
|
notes=[
|
|
"Exactly one identity field is required: `endpoint` for webpush, `token` or `client_id` for apns.",
|
|
"Matches the same identity priority as registration: `client_id`, then `token`, then `endpoint`.",
|
|
"Idempotent: unregistering an unknown or already-removed identity still returns 200 with `unregistered: false`.",
|
|
"Call this before logging out to stop delivery to the device that is logging out - the server has no way to know a browser tab or native app closed on its own.",
|
|
],
|
|
sample_response={"unregistered": True},
|
|
),
|
|
],
|
|
}
|